Precision Software Applications Silver Collection 1

home *** CD-ROM | disk | FTP | other *** search

/ Precision Software Appli…tions Silver Collection 1 / Precision Software Applications Silver Collection Volume One (PSM) (1993).iso / demos / mag6demo.exe / M600D2.ZIP / MAG6DOC.ZIP / MAGNUM6.DOC next >

Wrap

Text File | 1992-06-09 | 652KB | 16,723 lines

Gilmore Systems "MAGNUM BBS (r) SYSTEM FOR OS/2" Version 6.00C First Printing: September, 1989 This Printing: June, 1992 (C)Copyright Gilmore Systems - 1989, 1992 - All rights reserved - Gilmore Systems 1285 Falling Star Ave. Thousand Oaks, CA 91362 - USA Voice: (818) 706-9800 FAX: (818) 706-2785 BBS: (818) 706-9805 First Printing: September, 1989 This Printing: June, 1992 All programs and documentation written by: Chuck B. Gilmore Gilmore Systems (C)Copyright Gilmore Systems, 1989, 1992 - All Rights Reserved No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Gilmore Systems. Disclaimer Gilmore Systems makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Gilmore Systems reserves the right to revise this publication and to make changes from time to time in the content hereof without obligation of Gilmore Systems to notify any such person of such revision or changes. Under no circumstances will Gilmore Systems or the author be held responsible for any consequential or inconsequential damages resulting from the use or misuse of any furnished programs or documentation. Hayes is a trademark of Hayes Computer Products IBM is a trademark of International Business Machines, Inc. Intel is a trademark of Intel Corporation Magnum BBS is a trademark of Gilmore Systems Microsoft is a trademark of Microsoft Corporation. MultiTech is a trademark of Multi Tech Systems OS/2 is a trademark of IBM and Microsoft US Robotics and HST are trademarks of US Robotics This is a DEMO copy of "Magnum BBS"(r) Software for OS/2 This is a 2-node DEMO version (1 dialup node, 1 local/console node) The following restrictions have been built into the DEMO: - Up to 128 Users can be held in the USER database - Up to 128 Messages can be held in the MESSAGE database - Up to 128 Files can be held in the FILE database - Encryption of mail has been deactivated - Packing of the databases has been deactivated - Remote (Magnum-to-Magnum) mail has been deactivated - MILC commands @E2 and @E3 have been deactivated - Any third-party add-ons will not function - All optional ($) modules will not function: - Extended FileBase (provides up to 6,656 file areas) - Extended MsgBase (provides up to 6,656 conference areas) - Callback Module - Pipe module for OS/2 workstations - Pipe module for DOS 5 workstations - DEMO version has a serial# of 1111111111 (non-unique) - Limited technical support will be provided to those using the DEMO version. - Access to the "Magnum Sysop" file and message sections at our Thousand Oaks, California BBS location is restricted to Sysops using the commercial version. IMPORTANT NOTE! The remainder of this document is IDENTICAL to the commercial user manual. Be certain to keep in mind the restrictions given on the reverse page when using the demo (ie: Chapter 15 does not apply, MILC commands @E2 and @E3 do not apply, packing the databases do not apply, etc)! However, even with the restrictions imposed, we're sure you'll agree that Magnum BBS is perhaps the most powerful BBS software on ANY platform. The DEMO version alone will outperform what you've come to expect from BBS software. We encourage you to compare the features and functionality of Magnum BBS with any other, as well as our competitive pricing structure, technical support, and upgrade policies. In the meantime, enjoy the fully-functional demo (less the restrictions)! Table of Contents Page 1 TABLE OF CONTENTS MAGNUM BBS (r) system for OS/2 ..................................... 1-1 Optional add-on modules available from Gilmore Systems ........ 1-2 Configuring MAGNUM ==> start here <== ......................... 1-3 Configuring MAGNUM ............................................ 1-4 Directory Structure of MAGNUM ...................................... 2-1 Creating Subdirectories ....................................... 2-2 Order of Display Files ........................................ 2-7 Running MAGNUM BBS ................................................. 3-1 Starting MAGNUM BBS for the First Time ........................ 3-2 Starting Your FILES Database .................................. 3-4 Customizing MAGNUM - Display Files/MILC Commands ................... 4-1 Color Commands (@A) ........................................... 4-2 Branch (IF) Commands (@B) ..................................... 4-3 Screen Control Commands (@C) .................................. 4-5 Date Conversion Function (@D) ................................. 4-8 External and RJE Program Execution Commands (@E) ............. 4-10 Miscellaneous @E commands .................................... 4-13 Additional @E commands for 'Extended FileBase and MsgBase' ... 4-15 Include File Commands (@I) ................................... 4-16 Date Manipulation Commands (@J and @Y) ....................... 4-18 Call Command (@K) ............................................ 4-19 Security Level Commands (@L) ................................. 4-20 Match Filename in FILE DATAbase (@M) command ................. 4-21 Numeric (@N) Commands (ie: mathematics, I/O, etc) ............ 4-22 Other (Miscellaneous) Commands (@O) .......................... 4-27 Position (Label) Commands (@P) ............................... 4-30 Retain (@R), File (@F) and Query (@Q) MILC Variables @Z & @N . 4-31 Stack Keystrokes Command (@S) ................................ 4-33 Text to Log (activity) File (@T) ............................. 4-34 User Substitution Commands (@U) .............................. 4-35 View System Variables (@V) ................................... 4-39 Wait Command (@W) ............................................ 4-41 String (@Z) Commands (ie: String Logic, I/O, etc) ............ 4-42 Character Display - @\ command. .............................. 4-46 "Sysop Only" MILC commands: @$x, @&x, @!x, and @?x ........... 4-47 Advanced MILC Command Usage - Indirect Addressing ............ 4-49 Advanced MILC Command Usage - Enhanced Indirect Addressing ... 4-51 MAGNUM's Sysop Console ............................................. 5-1 The Bell, Forceoff, Switch and Info Commands .................. 5-2 The "* auto" and "* noauto" commands .......................... 5-4 The level, print and lockout commands ......................... 5-5 The active, time, announce/normal, and logon commands ......... 5-6 The endnow, end, shutdown and msg commands .................... 5-8 miscellaneous commands ....................................... 5-10 CHATting between SYSOP (you) and a USER via the Console ...... 5-15 TEST Mode (Testing your modem) ............................... 5-16 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 2 Table of Contents Back to Display Files & Subdirectories ............................. 6-1 The PROGRAM DIRECTORY ......................................... 6-2 The SESSION DIRECTORY ......................................... 6-4 The BULLETIN DIRECTORY ....................................... 6-10 The MENU DIRECTORY ........................................... 6-11 The HELP DIRECTORY ........................................... 6-12 The DISPLAY DIRECTORY ........................................ 6-13 The EXTERNAL DIRECTORY ....................................... 6-15 The RJE DIRECTORY ............................................ 6-16 The MESSAGE SUBDIRECTORY ..................................... 6-17 The WORK SUBDIRECTORY ........................................ 6-18 The SYSOUT SUBDIRECTORY ...................................... 6-19 The USER SUBDIRECTORY ........................................ 6-20 Using Magnum BBS as a USER ......................................... 7-1 The MAIN MENU ................................................. 7-3 The MESSAGE MENU .............................................. 7-9 The FILES MENU ............................................... 7-15 The SYSOP MENU ............................................... 7-25 The RJE MENU ................................................. 7-36 Magnum's ACE (Automatic Command Execution) Event Handler ........... 8-1 The MBBSEXEC Sysop Maintenance Utility Program ..................... 9-1 MBBSEXEC Field Names .......................................... 9-5 Field Names for the USER Database ............................. 9-6 Field Names for the MSG Database .............................. 9-9 Field Names for the FILE Database ............................ 9-10 Field Names for the RJE Database ............................. 9-11 Field Names for the UTILIZ Database .......................... 9-12 Syntax and Construction of an MBBSEXEC program ............... 9-13 The Assignment Statement ..................................... 9-15 Comparison Statements (IF) ................................... 9-16 Branch Statements (GOTO) ..................................... 9-17 Date Fields are Special Cases ................................ 9-19 Mathematics .................................................. 9-20 Processing a Single User Instead of the Entire Database ...... 9-21 MBBSEXEC 'Simple' Summary .................................... 9-24 MBBSEXEC Advanced Features ................................... 9-28 MBBSEXEC Advanced Features - the EXIT statement .............. 9-29 MBBSEXEC Advanced Features - Special Fields in USER database 9-30 MBBSEXEC Advanced Features - #LOG_FILE: ...................... 9-31 MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters 9-32 MBBSEXEC Advanced Features - Strings, Binary & Console Output 9-36 MBBSEXEC Advanced Features - the INPUT() statement ........... 9-38 MBBSEXEC Advanced Features - the WHILE() statement ........... 9-39 MBBSEXEC Advanced Features - The } ELSE { statement .......... 9-40 MBBSEXEC Advanced Features - Indirect Addressing (Indexing) .. 9-42 MBBSEXEC Advanced Features - Equating names for @TALLY/@STRING 9-44 MBBSEXEC Advanced Features -Writing/calling your own functions 9-45 MBBSEXEC Advanced Features -Setting the NEXT record to Process 9-48 MBBSEXEC Advanced Features - Executing an External Program ... 9-49 MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data 9-50 MBBSEXEC Advanced Features - Sample .MEX Programs ............ 9-53 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Table of Contents Page 3 MBBSEXEC -- Program Summary (All Sections) ................... 9-56 Magnum Utility Programs ........................................... 10-1 Supplied External and RJE Programs with Magnum BBS ................ 11-1 The NotePad Facility .............................................. 12-1 Setting up Additional Copies of Magnum on your LAN ................ 13-1 Remapping Directories for your Workstation ................... 13-3 For Systems using 'Extended File' and/or 'Extended MsgBase' ....... 14-1 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) ....................... 15-1 Closing Remarks ................................................... 16-1 Index .............................................................. I-1 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank MAGNUM BBS (r) system for OS/2 Page 1-1 Getting Started Rather than waste time with the standard commentary of copying files and creating directories, we'll assume you know what you're doing since a working knowledge of OS/2 and it's directory structure is needed. A semi-automated installation program is included which will create the subdirectories you specifiy and copy the appropriate files to those subdirectories. What You Need You'll need an IBM or compatible computer capable of running OS/2 version 1.2 or above, or OS/2 version 2.0 or above. Computers utilizing the Intel 8088, 8086 and 80186 microprocessors are not capable of running the OS/2 operating system. Computers utilizing the Intel 80286 microprocessors can run OS/2 version 1.x but not 2.x. Computers utilizing the Intel 80386 or 80486 microprocessor can run any version of OS/2. OS/2 runs in proctected mode on computers utilizing the Intel 80286, 80386 or 80486 microprocessor. You'll need approximately 5 Mb RAM for the operating system plus 1 node, 500K RAM for each additional node (these estimates are purposely high, you will probably need less). You will also need a modem for each node (your modem and cable must support CTS and RTS hardware handshaking, and must be capable of responding to the DTR signal). You will also need a text editor to configure Magnum's STARTUP files. The sample startup files included are located on the distribution diskette in the directory A:\MAGNUM\PGM_DIR and employ startup strings we've used on our BBS with the MultiTech 224Eh, US Robotics HST Dual Standard) and Hayes V.42 (V-Series) 9600 baud modems. OS/2 version 1.2 is the minimum operating system requirement for OS/2, however, we recommend using OS/2 version 1.3 or OS/2 version 2.0. It doesn't matter if you're running Standard Edition or Extended Edition edition (OS/2 1.x) or Extended Services (OS/2 2.x). NOTES The version you have of MAGNUM BBS is a multi-node version (even the 2-node version (1 dialup) is multi-node in that a remote user plus the sysop at the console can be online simultaneously). It can run with one or more nodes. IBM PS/2's can address COM1 thru COM3 with OS/2 1.x, or COM1 thru COM4 with OS/2 2.x. Non-PS/2's can only address COM1 and COM2. If you're using a version of Magnum that supports more serial ports than the operating system, you will need IBM's Artic communications coprocessor card and Quadron Service Corp's OS/2 comm device driver software (QCOM) to access the comports beyond COM2 (non-PS/2) or COM3 or COM4 (PS/2). Digiboard also supplies a communications coprocessor card and OS/2 device driver software. Both the Artic and Digiboard cards are available for AT and MicroChannel machines. The version number on your Magnum distribution diskette reveals how many nodes you have. If your version number is 6.00C5, the 5 after the C means you have 5 nodes, node 5 being your local (console) node, and all node numbers lower than 5 (1-4) can be used as dialup nodes. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-2 MAGNUM BBS (r) system for OS/2 Optional add-on modules available from Gilmore Systems Additional Incoming DIAL-UP Lines via LAN The version you have is "LAN ready". You can purchase and set up additional copies of Magnum BBS to be run on other workstations to provide dial-up (modem) support and share the databases with the main BBS (server). Installing the same copy of Magnum BBS at other workstations will not work (each workstation requires its own serialized copy of Magnum BBS software). If you're installing more than one copy of Magnum BBS for your network, make sure your PROGRAM DIRectory, SYSOUT DIRectory, and WORK DIRectories (described later in this chapter) are unique for each workstation. Contact Gilmore Systems for pricing information relating to additional workstations. Additional Incoming LOCAL (modemless) Lines via LAN Pipe Modules The version you have is "LAN ready". With the purchase of our optional Pipe Modules, you can log onto Magnum BBS from OS/2 or DOS 5 workstations. IBM's LAN Server, Microsof'ts LAN Manager, Banyan Vines, or any other LAN software supporting "named pipes" will work with our pipe modules. With our pipe modules, any node(s) on your current BBS can be set up as a "pipe" node instead of a "modem" node to allow pipe access. Those logging on via "pipe", are treated as any remote modem caller, thus system security is maintained. Extended File and Message Bases Magnum BBS is supplied with the main MessageBase and FileBase (MsgBase 0 and FileBase 0) built in. Each FileBase has 26 file 'areas' (A-Z), and each MsgBase has 26 message conference 'areas' (A-Z). We offer both an 'Extended MessageBase' and an 'Extended FileBase' module which extends Magnum's capabilities. The 'Extended FileBase' module, extends Magnum's FileBase capabilities from 1 FileBase of 26 areas to up to 256 FileBases of 26 areas each for a total of 6,656 file 'areas'. The 'Extended MessageBase' module, extends Magnum's MessageBase capabilities from 1 MessageBase of 26 message conference areas to up to 256 MsgBases of 26 areas each for a total of 6,656 message conference 'areas'. CallBack Module For the ultimate in security, our optional CallBack module will allow Magnum to 'call back' your users after they log onto your system. It can be set up to provide 'mandatory' or 'courtesy' callback on an individual basis (only those users you specify in a 'callback list' will be considered for CallBack). Although CallBack will work fine on a node which is used for incoming calls, we strongly recommend dedicated CallBack node(s) depending on how much the callback facility will be used. In the event that all CallBack nodes are busy (in use), the CallBack module will queue up to 100 callers at a time for CallBack. Contact Gilmore Systems for pricing information on optional modules. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-3 Configuring MAGNUM ==> start here <== This document is a guide to help new Sysops through the confusion of setting up a new BBS. Since experience has shown that all new BBS sysops want to start running their new BBS program *yesterday*, we'll get right down to the business of system setup. Your hardware should enable you to run OS/2 version 1.2 or above, or OS/2 2.0 or above. A safe memory requirement is 4-5 Mb just for the OS, 1 Mb for the parent process and 500K for each node you wish to run. If you de-activate the DOS compatibility box (OS/2 1.x), you will have more free RAM. If you de-activate the print spooler you will also have more RAM. If you run MAGNUM as a fullscreen text app, you will have more RAM - if you run it as a windowed text app, you'll have a little less RAM. Firstly, you will need to tell MAGNUM how you want your directories set up, which directories are for what, etc. ------------------------------------------------------------- NOTE: There are 7 Magnum versions: 2-node, 3-node, 4-node, 5-node, 9-node, 13-node and 17-node (number of dialups = nodes-1). This manual assumes you are using the 4-node version (the most popular). The highest node number (2 for 2-node, 4 for 4-node, etc), is the LOCAL (console) node. -> Since this document assumes 4-node version, ANY reference in <- -> this document to node 4 should be replaced with your high <- -> node (2, 4, 9, for example). <- ------------------------------------------------------------- Just like writing a program or a letter, you need a text editor to modify or create your configuration source files. You can have up to 4 configuration text files with MAGNUM with a filename format of STARTUP.X where X is the node you are defining. In other words, the file STARTUP.1 defines the node1 configuration, STARTUP.2 for node2, etc. STARTUP.4 (assume 4-node version) is not really a dial-in node, but the definition for the local (console) or virtual comport. The DEVICENAME for all STARTUP.x files except STARTUP.4 (local node) specifies which device is to be used for that node (ie: COM1, COM2, etc). Once you have modified the startup file(s) to your liking, you will need to "compile" these configuration files with MAGNUM's BBS compiler - MAKEMBBS.EXE but that will be at a later point. In the meantime, lets discuss the configuration text file itself. You may begin by copying the STARTUP.x files onto your hard disk from the sample ones supplied on the distribution diskette. These files are located on diskette in the directory A:\MAGNUM\PGM_DIR and, assuming you're currently in a directory on your hard disk (and that your hard disk is the default drive), you can copy these files with the following command: COPY A:\MAGNUM\PGM_DIR\STARTUP.* MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-4 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM You'll also need to copy the following files for now: COPY A:\MAGNUM\PGM_DIR\MAKEMBBS.EXE COPY A:\MAGNUM\PGM_DIR\MINSTALL.EXE For simplicity's sake, lets assume you will set up your BBS with Node1 for starters. You will need to get the file STARTUP.1 into your favorite text editor and begin modifying it. The actual STARTUP.1 file you have is a copy of the STARTUP.1 file being used at the Gilmore System's BBS. If you have a serial port on your system that you do NOT wish to use for the BBS, then don't create a STARTUP file for it! IMPORTANT: > Although more detail about your remote callers can be ascertained by setting your modem up to return Numeric result codes, it can be a time-consuming process to set up. For a speedy set up, where you needn't worry about result codes, have your modem return Verbose (word) results. Numeric result codes are returned when V0 appears anywhere in your modem init strings; Verbose (word) results are returned when V1 appears anywhere in your modem init strings. Some modems have a dip switch which may also need to be changed to match the type of result code (Numeric or Verbose) you wish. > Make sure your modem responds to the DTR signal generated by the computer. Do NOT have the modem force the DTR signal high! > Make sure your modem is set to pass Xon/Xoff characters thru as data - Magnum will perform Xon/Xoff processing as needed. Starting at the top of the file (STARTUP.1) and working our way down, lets go through each of the parameters. All configuration commands are in the format of: KEYWORD: PARM ; Comment Simply, KEYWORD: is the name of the field you are defining, PARM is the value of the field, and the ; character starts a comment. A comment starting with the ; character remains a comment for the remainder of that text line. In order, here are the keywords and what they mean: ACTIVE - this keyword tells MAGNUM whether or not you want this node to be active. The acceptable parms are Y or N. If Y, then this node will become active when MAGNUM starts up. If N, MAGNUM will ignore this node and you are free to use the node for any other program such as a communications program (MagCom or Logicomm for example). MBBS_VERSION - this keyword will be used internally. You should leave this blank or accept the value already supplied. It will MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-5 Configuring MAGNUM be automatically supplied when you "compile" the configuration. PARENT_SERNUM - this keyword expects a serial number for its parameter. If you're running a Magnum system on one machine and with no LAN (or LOCALBBS.EXE modules), then simply provide the serial number of your BBS system to this parm. However, in preparation for a higher degree of network support, this parameter must be the serial number of your MAIN BBS system ...if you're running more than one Magnum system (MBBS.EXE) on two or more different machines networked together, then supply the MAIN serial# as this parameter for EACH STARTUP.x files on all machines. This also applies to all STARTUP.x files for the local logon modules (LOCALBBS.EXE) running on your network. Once you decide which serial# is to be considered your MAIN system, NEVER CHANGE THIS PARM!! Encryption of passowrds and messages is based on this serial number, so all systems accessing your databases must share the same PARENT_SERNUM. ENCRYPT_MAIL - this keyword expects a parameter of Y or N (for 'yes' or 'no', respectively). If Y, then all messages entered on Magnum will be stored on disk in encrypted form. Magnum will automatically present the messages in readable form when being read by an authorized user. Because of the read/write access to subdirectories on networks containing Magnum messages (mail), encryption became necessary in order to preserve overall system security (ie: so that user's won't be able to write programs to access the messages). Once you choose to activate message encryption, messages will be encrypted from that point on (or until you de-activate it). Messages entered without encryption (including all previous versions of Magnum) will remain unencrypted. If you use encryption for a while, then decide to change back to the non-encrypted fashion, the encrypted messages will remain encrypted (but will be transparent to you and your users). GEO_PRIVACY - this keyword expects a parameter of Y or N (for 'yes' or 'no', respectively). If Y, then Magnum will enforce Geographic Privacy by not allowing the user's geographic information to be displayed when: 1) Logging On (the "From City, State ? (Y/N) => " prompt supressed). 2) Will supress geographic information from main menu's "[U]ser Search". INACTIVITY_TIMER - this keyword expects a number in the range of 180 to 1800. This number will indicate the amount of time (in seconds) in which the system will automatically force a remote user off of the system due to inactivity. Prior to this version, 240 was MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-6 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM hard-coded (4 minutes). Whatever number you choose, the system will issue a warning message to the remote user 60 seconds prior to the automatic logoff. NOTES: - For best results, supply a parameter which is a multiple of 60. - The inactivity timer applies once a user has actually logged onto the system. If the user has not responded the "Login" prompt within 3 minutes, the system will terminate the session. A user is considered to be logged on if one of the following is true: - The user is an existing user (in user database) and has properly entered their password. - The user is a NEW user (not in user database) and has completed the new user initial questions, at which time the "ID /xxx successfully added to user database" message appears. TRACK_UTILIZATION - this keyword expects a parameter of Y or N (for Yes or No, respectively). If the parameter is Y, utilization tracking for that node of your BBS will be stored in a utilization database file UTILIZ.DAT in the SESSION DIRectory associated with that node. Supply Y to the TRACK_UTILIZATION: keyword in all STARTUP.x files who's nodes you want tracked. Utilization tracking is stored as one record for each session (logon) that takes place for any node who's TRACK_UTILIZATION: parm is set to Y. MBBS_MODEM - this is where you supply a short (up to 25 characters) description of your modem. MBBS_COUNTRY - this is where you supply the name of your country (up to 20 characters). When new users log onto your system, this will be displayed to them as the default country when they are asked for their address information. DATEFORMAT - Supply a U for United States, or an E for European date formats. This is for reporting purposes - the date format your users choose is independent of this field. SERVERNAME - Optional. If you're using a LAN, supply the server name in this field, otherwise leave the field blank or don't supply the SERVERNAME: keyword at all. Although this field exists, it is not used by Magnum at this time. PRTY_CLASS - Optional. Allows you to change the priority class of a Magnum session. PRTY_CLASS can range from 0 to 4. 0 is generally not used since it indicates no change. 1 is the "Idle Time" class which is not recommended for BBS operation. 2 is the "Regular" class (the default for remote callers). 3 is "Time Critical" which can seriously slow MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-7 Configuring MAGNUM down all other sessions. 4 is the "Foreground" class. Unless you're familiar with multi-tasking time classes and priorities, we suggest you not supply this keyword or any parameters. The default will be class 2 for remote sessions, class 1 for console sessions. NOTE: This keyword is intended for system administrators fine-tuning Magnum when used with the optional Pipe Modules. PRTY_LEVEL - Optional. Allows you to change the priority level within a class. PRTY_LEVEL can range from 0 to 31. 0 is the lowest level of a time class, while 31 is the highest level. The lower the number, the lower the amount of time OS/2 allocates to the program. Unless you're familiar with multi-tasking time classes and priority levels, we suggest you not supply this keyword or any parameters. The default will be level 0 for remote sessions, level 31 for console sessions. NOTE: This keyword is intended for system administrators fine-tuning Magnum when used with the optional Pipe Modules. YMODEMG - Accepts a parameter of Y or N. If Y, Magnum will allow all users to be able to use the Ymodem-G protocol. If N, Magnum will only allow those with Error-Correcting modems (ie: MNP4, V.42, LAP, etc) to use Ymodem-G. Ymodem-G is a file transfer protocol that relies on an error-correcting modem to perform any error corrections. The nature of the protocol is to abort if the modem does not correct an error. If your modem is set up to return Numeric result codes, Magnum can ascertain whether the remote caller is using an error-correcting modem. On the other hand, the easiest way to configure Magnum is to have your modem return Verbose (word) result codes, and supply Y as the YMODEMG parameter. This way, you can omit the RC_xxxxx and ERC_xxxxx keywords described later on in this section. Most other BBS's are set up this way, however, Magnum does give you the choice for allowing more detail. CMDIO - Optional. Value can range from 0 to 255. Refer to the definition of CHILDREN.BBS in chapter 2 and how to set the @N0 value for instructions on how to determine what the value should be. This value will be used to set how I/O is performed when CMD.EXE is run as a child of Magnum via the "[O]perating System/2" selection of the Sysop menu. If you leave out the CMDIO keyword, the default will be 5. VERBOSE_CONNECT - Optional. If you plan on using Verbose (word) result codes (V1 appears somewhere in one of your modem init init strings, and any related dip switches are set to insure verbose (word) results on your modem). Most modems return "CONNECT xxxxx" when a connection is made. Some modems, however, return "CARRIER xxxxx" for MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-8 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM the baud rate of the connection (such as the Hayes V-series and Ultra, for example). Depending on which one your modem returns for baud rate connection, you'll need to supply one of the following: VERBOSE_CONNECT: CARRIER or VERBOSE_CONNECT: CONNECT If you omit this field, Magnum will take whichever the modem returns first (CARRIER or CONNECT) which may not reflect an accurate baudrate. For example, Hayes V-Series & Ultra return CONNECT xxxxx (where xxxxx is the DTE baudrate, the speed of Your computer to Your modem), and returns CARRIER xxxxx (where xxxxx is the DCE baudrate, the speed of Your modem to the Remote modem). ANNOUNCE_ONLY - the acceptable parms are Y or N. If Y, MAGNUM will treat this node as an announce-only node. If N, MAGNUM will treat this node as a regular BBS node. If announce only, it will answer the phone, display a file you create and hang up (See ANNOUNCE.x in chapter 2). NODE - although the extension of the filename (STARTUP.1 for example) indicates which node you are configuring, this parameter is mandatory and acts as a double check. (Note: In previous versions this used to be the COMPORT parm - please note the change). IMPORTANT: You must also have unique WORK DIRectories for each STARTUP.x file (described later on for keyword WORK_DIR). DEVICENAME - This parameter is the name of the device you'll be using for the serial port of this node. Device names are usually COM1, COM2, etc but can be any other supported device (ie: the Octoport card uses device names of AUX0, AUX1, etc). This field accepts up to 30 characters. If you're running under a LAN (ie: Lan Server or Lan Manager for example, you can supply the name of a redirected serial port. BAUDRATE - This parameter can range from 110 to 19200. The acceptable values are: 110, 150, 300, 600, 1200, 2400, 4800, 9600 and 19200. This does not necessarily mean the modem's baud rate, but the speed with which the computer talks to your modem. Some modems such as the USRobotics HST Couriers and the Multitech to name a few, can communicate with the DTE (computer) at a much higher baud rate than the actual baud rate of the modem over the phone lines. NOTE: As of this writing, the COM0x.SYS device driver MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-9 Configuring MAGNUM supplied with OS/2 only supports a maximum of 19200. If you're using a 3rd-party communications coprocessor such as IBM's Artic Card in conjunction with Quadron Service Corp's QCOM device driver, or if you're using the Digiboard communications coprocessor in conjunction with their OS/2 COM device driver software, you can supply a value of 38400 baud in this field. PARITY - for normal BBS communications, parity should be set to N (none). Other choices are E (even), O (odd), M (mark), S (space). DATABITS - for normal BBS communications, databits should be 8. Other choices are 7, 6 and 5. STOPBITS - for normal BBS communications, stopbits should be 1. Other choices are 1.5 and 2. WAITCARRIER - for normal communications, this should be 30, although the acceptable range is 1 to 255. This is the number of seconds Magnum waits for a result code from the modem once it's answered the phone. If no response within the time limit, it hangs up the phone and resets the modem for the next caller. NOTE: If your modem uses the "AT" command set, register S7 should match this parm. MODEMRESET - This is usually "AT Z" (without quotes). This is the string your modem requires for a reset. IMPORTANT: Some modems are configurable as to wheter to reset from factory settings or NRAM. Set your modem to reset from NRAM. If your modem is not configurable and resets from factory settings, simply supply "AT" (without the quotes). If you're not sure, or things aren't resetting right, supply "AT" (without the quotes). STARTUP1 - This is the initialization string for your modem. There are 3 initialization strings. Every modem is different, and even identical modems can have different startup strings. If you are following our example STARTUP.X files, our STARTUP.1 file is for a MultiTech 224E modem, while our STARTUP.2 file is for a US Robotics Dual Standard modem (the older, v.32 but not v.32 bis modem), and our STARTUP.3 file is for a Hayes V.42 9600 baud modem. There are 3 such strings to accomodate the lengths. Be careful, some modems may only accept up to 40 characters per string. -> NOTE 1: In any of these strings, ensure V1 appears if you plan on using Verbose (word) results. Otherwise, ensure that V0 appears if you plan on using Numeric result codes. Also make sure that if your modem has any dip swithces, that you set them to correlate with V1 (word) or V0 (numeric) depending on choice. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-10 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM -> NOTE 2: For the fastest possible setup with minimal time spent in your modem's user manual (especially if all this is new to you) follow these steps: a) Use Verbose result codes (V1 in any of your STARTUP strings). b) Supply Y to the YMODEMG parm described earlier. c) Delete all keywords starting with RC_nnnnn, ERC_nnnnn, ERCA_nnnnn, and ERCB_nnnnn. The n's merely represent digits. These keywords are described later in this chapter, and appear later on in your STARTUP.x file. STARTUP2 - see STARTUP1 STARTUP3 - see STARTUP1 (this string usually ends with &W) REINIT - this is the command your modem needs to reinitialize itself after every caller. This is usually ATZ. NOTE: ATZ is interpreted differently on some modems than others. To some modems, it means to reinitialize from nonvolatile ram (NRAM or NVRAM), to others it means to reset completely (factory settings). If you're not sure, set this field to just AT and nothing else (don't append the Z). DELAY1 - this is the delay (in miliseconds) of how long MAGNUM should wait after sending your STARTUP1 string before it should send the STARTUP2 string to your modem. This will vary with your CPU speed, modem, the speed with which your computer converses with your modem, and how fast your modem can process the string. DELAY2 - (see DELAY1) Specifies (in miliseconds) how long MAGNUM should wait after sending your STARTUP2 string before it should send the STARTUP3 string to your modem. DELAY3 - (see DELAY1) Specifies (in miliseconds) how long MAGNUM should wait after sending your STARTUP3 string before continuing. DTELOCKED - as mentioned earlier, some modems can communicate with the DTE (computer) at a much higher baudrate than they can over the phone lines. For these modems, especially those with MNP (Microcom Network Protocol), you can increase efficiency (throughput) by locking the DTE. Answer Y to lock the DTE, or N not to. If N, the DTE speed will match that of the incoming callers baudrate. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-11 Configuring MAGNUM -> NOTE: If you're using a modem such as the US Robotics Dual Standard, the Intel V.32, Hayes Ultra, or just about any modem capable of v.32 (9600 baud) communications, supply 19200 for the BAUDRATE parm above, and Y to the DTELOCKED parm. If you'r using a coprocessor card such as Artic or Digiboard, supply 38400 baud to the BAUDRATE parm. See the BAUDRATE parm described earlier in this chapter. ANSWERTYPE - Accepts a value of A or R. MAGNUM can be configured to answer the phone, or it can let your modem answer the phone. If you select A for auto-answer, your modem will answer the phone and MAGNUM will respond once a connection is established because the modem will send MAGNUM a result code. If you select R for ring-detect, MAGNUM will issue the command to the modem to answer the phone. -> NOTE: For modems with the AT command set (Hayes, etc), you must have "S0=1" (without quotes) as part of your STARTUPx strings if you choose auto-answer, otherwise you must have "AT S0=0" (without quotes) as part of your STARTUPx strings if you choose ring-detect. RING-DETECT IS THE PREFERRED CHOICE! OPENMODE - Accepts a value of S or N. MAGNUM can open the communications ports as shared or nonshared. MAGNUM will work fine either way, however we strongly recommend that in a multitasking operating system such as OS/2, you choose N (nonshared). Choosing N guarantees that no other program will open the comport and ruin a session in progress. Choosing S will cause MAGNUM to open the port as shared, meaning any other program can also open that same comport. ANSWERCMD - Modem answer command string. For AT command sets (Hayes & compatible), the command is ATA. ONHOOK - Modem command to go onhook (hang up). AT command sets: AT H0 OFFHOOK - Modem command to go offhook (pick up the phone but don't answer it) - AT command sets: AT H1 NOTE: If you wish to turn off the speaker at this point, supply AT H1M0 ESC_CMDMODE - the command string which places the modem in command mode. AT command sets: +++ ESC_GRDTIME - Guard time (in miliseconds) for the modem to recognize the string for ESC_CMDMODE and place the modem in command mode. GO_ONLINE - the command string which causes the modem to go back online from a ESC_CMDMODE escape. AT command sets: AT O MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-12 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM END_OFFHOOK - acceptable parms are Y or N. If Y (yes), the modem will place the phone offhook when you decide to end the MAGNUM BBS program (the modem must remain on in order for this to work) by sending the commands you specified in the OFFHOOK parameter described earlier. If N (no), any remote callers will not get an answer - the phone will continue to ring until the remote caller's modem hangs up. --- IF you're using the "fast" setup (Verbose result codes, Y to the YMODEMG keyword, and supplied the VERBOSE_CONNECT parameter), then follow these steps: a) Supply N to the ERRORCHECK keyword (ie: ERRORCHECK: N) b) Delete (deletion is optional) all keywords starting with RC_ or ERC_ or ERCA_ or ERCB_, and disregard the description of those keywords below. RC_110 - result code returned by the modem for a 110 baud connection RC_150 - result code returned by the modem for a 150 baud connection RC_300 - result code returned by the modem for a 300 baud connection RC_600 - result code returned by the modem for a 600 baud connection RC_1200 - result code returned by the modem for a 1200 baud connection RC_2400 - result code returned by the modem for a 2400 baud connection RC_4800 - result code returned by the modem for a 4800 baud connection RC_9600 - result code returned by the modem for a 9600 baud connection RC_12000 - result code returned by the modem for a 12000 baud connection RC_14400 - result code returned by the modem for a 14400 baud connection RC_19200 - result code returned by the modem for a 19200 baud connection ERRORCHECK - answer Y (yes) to indicate an error-correcting modem is being used (ie: a modem with MNP,ARQ and/or LAP protocol), otherwise answer N (no). ERC_110 - modem result code for error-correction connect at 110 baud ERC_150 - modem result code for error-correction connect at 150 baud ERC_300 - modem result code for error-correction connect at 300 baud ERC_600 - modem result code for error-correction connect at 600 baud ERC_1200 - modem result code for error-correction connect at 1200 baud ERC_2400 - modem result code for error-correction connect at 2400 baud ERC_4800 - modem result code for error-correction connect at 4800 baud ERC_9600 - modem result code for error-correction connect at 9600 baud ERC_12000 - modem result code for error-correction connect at 12000 baud ERC_14400 - modem result code for error-correction connect at 14400 baud ERC_19200 - modem result code for error-correction connect at 19200 baud ERCA_110 \ Some modems require additional error-correcting result . \ __ codes (ie: a different one for MNP, one for LAP, etc). . / If your modem requires additional codes, they go here. ERCA_19200 / Leave blank if not used by your modem. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-13 Configuring MAGNUM ERCB_110 \ Some modems require additional error-correcting result . \ __ codes (ie: a different one for MNP, one for LAP, etc). . / If your modem requires additional codes, they go here. ERCB_19200 / Leave blank if not used by your modem. - - - Directory Paths - - - Now we can go into the BBS directory paths. Directory paths are FULL paths including the drive letter. For instance, E:\MAGNUM\PGM_DIR is a valid pathname, while MAGNUM\PGM_DIR is invalid (no drive and no root path). Not every path has to be unique, although we recommend it for maintenance sake, but technically you can use the same path in more than one place. Each pathname can be up to 65 characters in length (including the drive letter). You can optionally end your pathname with the \ character but it doesn't matter - if you don't, MAGNUM appends one internally anyway. PROGRAM_DIR - This defines the directory which holds the actual MAGNUM BBS program(s). We use E:\MAGNUM\PGM_DIR NOTE: The PROGRAM_DIR parm should be on the same logical drive as the WORK_DIR parm (below). SESSION_DIR - This defines the directory which holds session data. We use E:\MAGNUM\SES_DIR BULLETIN_DIR - This defines the directory which holds bulletins and newsletters. We use E:\MAGNUM\BUL_DIR MENU_DIR - This defines the directory whcih holds any menus you create. We use E:\MAGNUM\MNU_DIR HELP_DIR - This defines the directory which holds the help files. We use E:\MAGNUM\HLP_DIR DISPLAY_DIR - This defines the directory which holds the display files. We use E:\MAGNUM\DSP_DIR EXTERNAL_DIR - This defines the directory which holds external programs. We use: E:\MAGNUM\EXT_DIR RJE_DIR - This defines the directory which holds RJE specific stuff. We use: E:\MAGNUM\RJE_DIR MSG_DIR - This defines the directory which is the parent to the message subdirectories. We use: E:\MAGNUM\MSG_DIR WORK_DIR - This defines MAGNUM's work directory. We use: E:\MAGNUM\WORK_DIR\1 for node 1 (STARTUP.1), E:\MAGNUM\WORK_DIR\2 for node 2 (STARTUP.2), etc. NOTES: - Each node should have its own, unique WORK_DIR - The WORK_DIR should be on the same logical drive as the PROGRAM_DIR MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-14 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM USERS_DIR - This defines the directory MAGNUM uses for logging answers for user-generated questionairres, and user NotePads. We use: E:\MAGNUM\USER_DIR SYSOUT_DIR - This defines the directory for system output (ie: Activity logs, chat logs, user responses to questionnaires, etc). Now comes the file directories. As with the other directories, you have up to 65 characters each, and must include a full path including drive. You can have up to 26 file directories labeled A to Z. You should try to give descriptive names to the directories. The keywords for these entries are FILEDIR_A thru FILEDIR_Z. See the example STARTUP.X file for the way we use them. After defining the file subdirectories above, you now need to define descriptions. You have up to 40 characters each to describe the contents of the directories. You can have up to 26 file directory descriptions. The keywords for these entries are FILEDES_A thru FILEDES_Z. See the example STARTUP.X file for the way we use them. You can have up to 26 message areas labeled A thru Z. Whatever subdirectory you supplied for the MSG_DIR parm, the setup program (MINSTALL.EXE) will create 26 subdirectories under the MSG_DIR directory. (ie: E:\MAGNUM\MSG_DIR\A ... E:\MAGNUM\MSG_DIR\Z). More on the MINSTALL.EXE program later - for now, the completion of editing the STARTUP.X files is crucial. Like the FILEDES_x parm, the MSGDES_x parm is similar. You give descriptive headings for each of the MSGDES_x parms (up to 40 chars each). See our STARTUP.x file(s) for examples of how we use them. Now comes the BBS Parameters: BBS_NAME - this is where you give your BBS a name (up to 40 characters). BBS_STARTED - this is where you tell MAGNUM what date you'd like MAGNUM to show users as the starting date of the BBS. TTL_CALLS - this is where you tell MAGNUM how many calls your BBS has taken at the time of this creation. Ordinarily this would be 0, but some sysops switching systems want to display how many calls THEY'VE had - not this particular software. SYSOP_FIRST - the sysop's first name SYSOP_MIDDLE - the sysop's middle name or initial (LEAVE BLANK IF NONE) SYSOP_LAST - the sysop's last name PAGING_BEGIN - the sysop's beginning paging time (in seconds from midnight). To calculate seconds from midnight (00:00), take the desired time in military format (ie: HH:MM or MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-15 Configuring MAGNUM 14:30 for example) and use the formula (HH * 3600) + (MM * 60). PAGING_END - the sysop's ending paging time (in seconds from midnight). See the description of PAGING_BEGIN to derive seconds from midnight. OPEN_BOARD - Y=sysop is running an open board (anyone can call). N=sysop is running a closed board - sysop must pre-enter the users who are allowed access to the board. Pre-entering users in a closed system is accomplished by setting up the local node as an open system, and logging on from the console as the new user. REUSE_DEL - If you delete users, this option will let you assign a new user to an old user's ID. Answer Y to re-use deleted ID's. Answer N not to re-use deleted ID's. Bear in mind that Magnum's user database is not packable, meaning that if you have deleted users they will remain as deleted users forever (or until you change this parameter to Y and recompile the STARTUP.x file with the MAKEMBBS.EXE program). If you'll be setting this field to Y (yes), users will only be re-used if: - They are deleted, and - the REUSE field of the deleted record is Y, and - the new (replacement) user has the same first letter of their last name as the deleted user. NEWUSER_LVL - this parm tells MAGNUM what security level to assign to a new user. This can range from 0 to 9999. CONFIRM_NEWRESP - Optional. Supply Y (yes) or N (no). The default is N. If you supply N (no), Magnum will not confirm new user user logon responses with "Is this correct (Y/N) => " prompts when new users respond to the prompts of address, city, state, zip, country, telephone numbers, etc. Instead, the new user will have a chance to update their responses at the end of all of the new user logon questions. We recommend the default of N. This keyword exists only for compatibility with previous Magnum versions which confirmed every response. The confirmation of every response however, is frustrating and extraneous. GET_PHONE - Y=ask new users for their telephone numbers. N=don't ask. GET_DOB - Y=ask new users for their date of birth. N=don't ask. GET_COMPUTER - Y=ask new users for the computer brand. N=don't ask. GET_QUESTION - Y=force new users to fill out the new user's questionairre. N=no questionairre. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-16 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM GET_COMPANY - Y=Prompt user for whether they have a company name and collect the name of their company if they do. N=Do not prompt for company and do not collect company name information. GET_ADDRESS - Y=Collect mailing address information from the user. N=Do not collect mailing address information. GET_DATEFMT - Y=Ask new user for date preference (US or European). N=Use System Date Format for new user (obtained from the DATEFORMAT keyword described earlier). The user can change this later on through the [E]nvironment section of the main menu. GET_INTERESTS - Y=Ask new user for their areas of interest (for cross-reference capability). N=Do not ask new user for areas of interest. The user can change this later on through the [E]nvironment section of the main menu. MILC_CHAR - Optional. The parm you supply for this keyword will override the default MILC command character of '@'. MILC is the embedded command language Magnum uses in your display files. These embedded commands begin with a special character known as the MILC_CHAR. NOTE: characters with decimal values of 0 to 32 (hex 0 to hex 20) will not be accepted. Alphanumeric characters (A-Z, a-z, 0-9) and punctuation characters will NOT be accepted: !,.?"':;() CAUTION: If using someone else's MILC command file (from another BBS), chances are very high that they're using the @ character; you must be sure to change this to the MILC command character you define for your system. If you'll be overriding the MILC command character, use extreme caution in selecting a new character! Avoid the use of characters which may appear within a normal message (ie: %$#*[]{}\/<>+-&). Try to pick a not-so-common character such as the ~ or ^ character. MORE_ADJUST - Optional. The "- More -" prompt appears after each screenful of text if the user wishes it. A screenful of text is defined by the user. For example, if the user specifies 25 lines/screen, then Magnum will display 25 lines of text and the -More- prompt will appear on line 26 thus scrolling one line of previous text off of the screen on a 25-line CRT. The value you supply here will adjust for this. For example, if you supply -1, then the user's lines/screen will effectively become (25-1) or 24. This keyword is optional, and carries a default of 0 if not specified. Recommended values are -3 to 2. DATEPROMPT_MIXED - Optional. Takes a parameter of Y or N. Supply Y to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-17 Configuring MAGNUM have Magnum supply date prompts in mixed case (ie: mM/dD/yyyy or dD.mM.yyyy), or N to supply date prompts in uppercase (ie: MM/DD/YY or DD.MM.YYYY). This keyword is optional, the default is N. SHOW_CALLERNUM - Optional. If you supply Y to this keyword, Magnum will function as usual. If you supply N to this keyword, Magnum will suppress the "You are the nth caller on node x" message when someone logs on. SHOW_DLS - If you supply Y to this keyword, Magnum will function as usual. If you supply N to this keyword, Magnum will suppress the information on the number of Downloads on each file during any file listings. REMOTE_MAIL - Optional. If you don't plan on using remote mail, you should either supply N to this keyword, or leave the keyword out alltogether (default is N). This field applies only to NEW (first time) users. This is where NEW users get their RMAIL field in their record from (see the RMAIL field in the chapter on MBBSEXEC); in other words, if you want new users to be able to use the remote mail facilities immediately, supply Y to this keyword. NOTE: Existing users on the system will be unaffected by this field. Write a .MEX file for bulk update of existing users (see MBBSEXEC). NEWUSER_TIME - new user's daily time limit (in minutes) LINES_SCREEN - new user's default for number of lines per screen LOWEST_BAUD - lowest baud rate allowed FILE_U_AREAS - file upload areas assigned to new user (use letters A-Z) FILE_D_AREAS - file download areas assigned to new user (letters A-Z) FILE_L_AREAS - file list areas assigned to new user (use letters A-Z) MSG_R_AREAS - message read areas assigned to new user (use letters A-Z) MSG_W_AREAS - message write areas assigned to new user (use letters A-Z) MSG_L_AREAS - message list areas assigned to new user (user letters A-Z) DISP_CMDS - "Display" commands (MILC) user is allowed to imbed in messages s/he enters. RJE_AREA - area of file section designated for RJE results (ie: for use with the [F]ile menu's [M]ake command and for placement of resultant files from running RJE jobs). COMMENT_AREA - area of message section for "comments to/from sysop" STARTUP_TYPE - Session Startup (F=Fullscreen, W=Windowed) for this node FILEDES_AREA - area of message section for extended file descriptions PRIVMSG_AREA - area of message section for private system messages MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-18 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM (messages generated by Magnum to a user). PRIVATE_MSGS - Y=private messages are allowed, N=private messages NOT allowed. NOTE: Comment to Sysop from main menu is *always* a private msg regardless of this setting. VERIFY_PHONE - Range is 0 to 255. If 0, phone number is not verified. If non-zero, the system will ask the user for phone number verification after every Xth call. (ie: if X is 5, the system will verify phone numbers for every 5th call the user makes to the system). This is an additional security check. NOTE: If the GET_PHONE parameter is N, then the VERIFY_PHONE parameter MUST be set to 0. VERIFY_DOB - Similar to VERIFY_PHONE except it verifies date of birth after every Xth call the remote user makes. If 0, no verification is asked for. NOTE: If the GET_DOB parameter is N, then the VERIFY_DOB parameter MUST be set to 0. DEL_MSGS - Y=user is allowed to delete messages, N=user cannot delete messages. NOTE: Y only allows user to delete messages addressed to/from his/her own user id. LOG_MSGS - Y=report each message read to the activity log - this can make your activity logs very large very fast - especially with a large message base. N=do NOT record each message read to activity log (preferred). LOG_TIME - Y=prefix the time (hh:mm:ss) to each entry made in the activity logs in addition to start time of user session. N=do not prefix time to entries made in activity logs (start time of each user session is automatically entered in activity logs). SYSOP_LVL - the security level assigned to the Sysop. can range from 1 to 9999. This should be the highest security level of all of the users of the board. In our case, we're using a level of 1000. SYSOP_MAIL_LVL - Security Level needed to read private sysop mail. This would be for assistant sysops who you might want to be able to read private mail addressed to "sysop", but without necessarily having any other sysop priveleges. Level 900 is what we're using. DISPLAY_PW_FILES - Y=password protected files show up in the file listings. N=password protected files do NOT show up in file listings. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-19 Configuring MAGNUM UPLOAD_COMP - range is from 0 to 255. If X is 0, no upload compensation is granted, otherwise, upload compensation is X times the number of minutes spent uploading a file. For example, if X is 3, then if a user spends 5 minutes uploading a file, then 5 times 3 = 15. Therefore, the user would receive 15 minutes of upload credit in the form of 15 minutes of additional time left on the system. MSG_COMP - similar to UPLOAD_COMP, X can range from 0 to 255. X is in units of seconds per word. In other words, if X were 3 and the user entered a 100-word message, then 100 times 3 = 300. Therefore, the user would receive message compensation of 300 seconds (5 minutes). Actual compensation is rounded to the nearest minute. 1 minute and 30 seconds rounds to 2 minutes, whereas 1 minute and 29 seconds rounds to 1 minute. We have our system set to 1. UL_DL_RATIO - a ratio counter for number of files downloaded. If X is set to 10, then for every 10 files a user downloads, the system expects 1 file in return. The system will not allow further downloads until the ratio is met. If X is set to 0, no ratio is required - the user can download to their heart's content. DL_BYTES - maximum bytes a user can download per day (see TIME_UNIT). DL_FILES - maximum files a user can download per day (see TIME_UNIT). MAX_TIME_CALL - maximum time limit for any caller (in minutes). This field specifies how long any individual call can last regardless of security level or time allowed for the period. For example, if X is 60, then no caller will be allowed to exceed 60 minutes for any given call even though they might be allowed more than 60 minutes per day. The caller must either log off at the end of 60 minutes or be forced off by the system. The caller can call right back and be allowed another 60 minutes. This is to ensure that no caller ties up the system without giving someone else a chance. DAILY_TIME - new user daily time limit (in minutes). TIME_UNIT - Can be one of D (daily), W (weekly), M (monthly) or Y (yearly). If D, everything is as expected. If W, all parameters are internally multiplied by 7. If M, all parameters are internally multiplied by the number of days in the current month. If Y, all parameters are internally multiplied by the number of days in the current year (365 or 366). Taking a weekly (W) user as an example, a newuser default of 30 minutes per day would translate to 210 minutes per week (30 times 7). The user could use all of this time up in one day and not be allowed back on the system until next week. The number of daily downloads allowed, etc are MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-20 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM all multiplied by 7. Although the period types of D, M, and Y have straightforward boundaries, W boundaries differ - for example, in 1989, January 1st fell on a Sunday, therefore, all W (weekly) boundaries will fall on a sunday for the remainder of 1989. For any given year, the boundary day which determines the change of week is the day that January 1st was for that year. This TIME_UNIT field is often referred to in the documentation as "period" or "period type". PRORATE - This parameter can be Y or N (yes or no). If Y, proration of any period type (TIME_UNIT) other than D (daily) will take place. This is best explained via example. If a user's period type is M (monthly), and the current month is June (30 days), then the user should have 30 times the daily parameters allocated. However, if PRORATE=Y, then if the user first calls the BBS on June 20, then MAGNUM will prorate the time left for actual days left in the month. In other words, June 20th means that only 10 days are left of the month, therefore, the user will only receive 10 times the daily allocation instead of the full 30. This proration will take place every logon. This may help lighten the extra load at the end of a period (week, month, year) when users scurry to get their time's worth in the last possible chance before a new period begins. PRINTER - A log is automatically kept by MAGNUM under the filename of ACTIVITY.X where X is the node number. This report can be routed to a printer or other device (or other file but that would duplicate the ACTIVITY.X file). If you are running more than one node, do NOT choose PRN as the device for each node unless you are using the print spooler. Supply "nul" (without the quotes) if you don't want anything printed (ie: if the ACTIVITY.X report is good enough for you). SUB_FILEDEL - This parameter can be Y or N (yes or no). If Y, Magnum will subtract 1 upload credit each time a user deletes a file they uploaded to the system. If N, Magnum will NOT subtract any upload credits from the user's upload counter. FREE_DL_AREAS - This parameter specifies file areas that a user can download from without affecting their upload/download ratio counter. If you're using an upload/download ratio (ie: wanting 1 upload for every X files downloaded), you can define which areas files can be designated as "free" downloads. For example, if your company runs a support BBS with updates of your software available for download (regardless of how many downloads the user performed to date), you would designate those area(s) here. If you specify "ACH" (without the quotes), then all files downloaded from file areas A, C and H will be considered "free". (Free, in the sense that the user's upload/download counter is not incremented). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-21 Configuring MAGNUM BLOCK_WRITES - This parameter can be Y or N (yes or no). If Y, Magnum will send text to the comport in blocks (rather than single bytes at a time) whenever possible. This will improve the performance and efficiency of Magnum. On the down side, "remote snoop" (where you can call your BBS remotely and snoop on any node currently online with a caller) may result in lost characters on your remote "snoop" screen. NEW_MAIL - This parameter fan be one of three: "A" (without quotes) will ASK the user (at each logon) if they wish for Magnum to scan the message base for any "unread mail". "F" (without quotes) will FORCE a mail check (no prompts, just the mail check). "B" (without quotes) will bypass any mail checking or mail checking prompts. VERIFY_GOODBYE - This parameter can be Y or N (yes or no). If Y, the system will ask the remote user if they're sure they wish to log off (if the user is sure, they'll be prompted as to whether they wish to leave a comment to the sysop prior to disconnecting). If N, the system will not ask the user if they're sure about disconnecting, and will not prompt for a logoff comment, it will just log the user off (the ending quote will still be sent if the quote file is present, and the GOODBYE.BBS file will also be sent if present). BADCMDMSG - Y=Issue Message for unauthorized menu commands, N=don't NOANSI - Y=Deactive ANSI color, N=ANSI color ok If NOANSI is set to Y, color escape sequences are not sent by Magnum regardless of the user's color settings. The user will be unable to change their color settings from the [E]nvironment option. The new ANSI message editor will still function by using all ANSI escape sequences except color. NOXFRTIME - Y=Timer inactive for file xfers, N=Normal BBS xfr operation If NOXFRTIME is set to Y, the timer is disabled during file transfers. For example, if a user has a 30-minute time limit per day, the timer will stop during file transfer, enabling the user to download for hours on end. After transfer(s) are completed, the timer starts again from where it left off before the transfer. This situation is ideal for those companies who provide updates/fixes to their software via Magnum and, since each download saves the company a few dollars in labeling, packaging, shipping, etc, enabling this option ensures that every caller will be able to download any/every file they need with a single call. NOTE: If you supply Y to the NOXFRTIME keyword, not only is the timer disabled, but the following checks MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-22 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM are also deactivated: - UL/DL ratio - Maximum K-bytes downloaded per period - Maximum Files downloaded per period - Time remaining for the period MAINMENU_HDR - Optional. Overrides the header (title) the user sees upon entry into the main menu. The default main menu header is "Magnum OS/2 BBS - Main Menu". If this keyword is supplied, it will override the main menu header with what you supply here. Example: MAINMENU_HDR: ABC Corp - Main Menu You may specify up to 60 characters. FILEMENU_HDR - Optional. Similar to MAINMENU_HDR but for file menu. MSGMENU_HDR - Optional. Similar to MAINMENU_HDR but for message menu. RJEMENU_HDR - Optional. Similar to MAINMENU_HDR but for RJE menu. SYSMENU_HDR - Optional. Similar to MAINMENU_HDR but for Sysop menu. CPUTYPE_OVERRIDE - Optional. If you specified Y to the GET_COMPUTER keyword described earlier, Magnum will prompt the user as to what brand of computer their using. This keyword can override that prompt with your own. For example, to find out what modem brand the user is using: CPUTYPE_OVERRIDE: What modem brand are you using You can supply up to 40 characters. Magnum will automatically append " => " (without quotes) when displayed to your users. The user can respond with up to 20 characters. The remainder of the configuration text file (STARTUP.x) allows you to define how you want menus to look. These are the internal menus which are dynamically built by MAGNUM. You'll see later how to create your own menu file, but internally, MAGNUM needs to know what security level gets to do what function, and what letter you wish to assign to the functions, and what descriptions you want for the functions. Menu definitions are as follows: KEYWORD: C,L,S where KEYWORD tells MAGNUM which function you are referring to, C tells magnum what letter of the alphabet you wish to use to call that function, L tells MAGNUM the minimum security Level needed to access that function, and S is a string up to 40 characters in length which gives a descriptive text of the function. See the sample STARTUP.X file for how we do it. For example, the "[Y]ell for Sysop" might better suit your taste as: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-23 Configuring MAGNUM MAINMENU_PAGESYS: P,5,[P]age the Sysop The above statement tells MAGNUM that P would call the function MAINMENU_PAGESYS if the user has a security level of 5 or greater. MAGNUM would show that part of the menu as: [P]age the Sysop However, if the user's security level is less than 5, then that part of the menu would not appear. In other words, only level 5 and above would see that menu selection. MAGNUM dynamically builds these menus according to the user's security level. Be careful not to duplicate call letters within a menu. In other words, it's ok to have a call letter of P appear in the main menu, the file menu, the message menu, etc - but P can only appear once within any individual menu (ie: You cannot have P for "[P]age Sysop" and for "[P]arms" in the same menu). The Descriptive text for commands (up to 40 characters) is completely up to the sysop configuring the system. the brackets surrounding the first letter of the description has no bearing whatsoever - it merely helps the user to know what command is what. "[M]essage Section" could just as easily be "M - Messages" or "M = MAIL" or "EMAIL ...........M" - whatever your preference. Be warned that MAGNUM generates a 2-column menu display such that column one is from phsyical columns 1 thru 40, while column two is from physical columns 41 thru 80. Although MAGNUM accepts descriptive text of up to 40 characters, you should maximize your text to 39 characters or less otherwise this is what can happen with text using all 40 characters: If in the first column, the last character (column 40) will appear immediately before the first character of the second column (column 41); Likewise, if the second column (41 thru 80) uses all 40 characters, then when the character on column 80 displays, certain displays will cause an automatic CR/LF, leaving a blank line between this menu choice and the next one. There are 5 menu sections - each with their own unique keywords as follows: --- MAIN MENU DEFINITIONS --- MAINMENU_MSG: takes user from main menu to the message menu MAINMENU_FILE: takes user from main menu to the files menu MAINMENU_RJE: takes user from main menu to the RJE menu MAINMENU_BULLETIN: takes user from main menu to the main bulletin file MAINMENU_QUESTION: takes user from main menu to the main question file MAINMENU_COMMENT: allows user to enter a private comment to sysop MAINMENU_PAGESYS: system pages the sysop MAINMENU_WHO: shows who's on the other nodes MAINMENU_CHAT: enters group chat mode MAINMENU_INITIAL: shows initial welcome screen(s) again (HELLO?.BBS) MAINMENU_USERS: takes user to the "search user database" area MAINMENU_PARMS: allows user to change parameters in their profile MAINMENU_STATS: shows system statistics MAINMENU_CHILD: takes user to the main "child" file (door menu) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-24 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM MAINMENU_NEWS: takes user to the main "news" file MAINMENU_GOODBYE: logs user off and disconnects MAINMENU_EXPERT: toggles expert mode on/off MAINMENU_HELP: displays help file for main menu MAINMENU_SYSOP: takes user into the sysop menu section MAINMENU_OPT1: displays file MAINOPT1.BBS from DISPLAY DIRectory MAINMENU_OPT2: displays file MAINOPT2.BBS from DISPALY DIRectory Be careful in setting up the security levels - if the security level for MAINMENU_GOODBYE is higher than the lowest person's security level, then the user with the lower security level will not be able to log off! S/he will have to break the connection at their end! Likewise, if MAINMENU_HELP is too high, users with lower levels will not be able to get help! Also, make sure that the MAINMENU_SYSOP level only allows YOU (or someone you trust) to access the Sysop menu, otherwise someone could cause a lot of damage to your system! --- Message Menu Definitions --- MSGMENU_QUIT: Allows user to quit msg section. return to main menu MSGMENU_UPDT: Allows user to change message area(s) MSGMENU_READ: Allows user to enter the "read messages" submenu MSGMENU_SCAN: Allows user to scan messages MSGMENU_ENTER: Allows user to enter a message MSGMENU_KILL: Allows user to kill (delete) a message addressed to or from their own ID. MSGMENU_SRCH: Allows user to perform a text search. MSGMENU_CHECK: Allows user to check for their own personal mail. MSGMENU_GOODBYE: Logs user off and disconnects. MSGMENU_HELP: Displays the help file for the message section. MSGMENU_OPT1: Displays file MSGOPT1.BBS from DISPLAY DIRecory. MSGMENU_OPT2: Displays file MSGOPT2.BBS from DISPLAY DIRectory. MSGMENU_BASE: Change Msg Base. Requires 'Extended MsgBase module'. --- File Menu Definitions --- FILEMENU_QUIT: Allows user to quit file section. Returns to main menu. FILEMENU_INFO: Displays detailed info on a file, including extended description if it exists. FILEMENU_LIST: Lists available files by section(s). FILEMENU_DL: Allows user to perform download(s). FILEMENU_UL: Allows user to perform an upload. FILEMENU_NEW: Allows user to perform a new files search by section and date FILEMENU_SRCH: Allows user to search file names and the brief description for a string of text. Can filter by date too. FILEMENU_STATS: Displays user's statistics for the period and in ttl FILEMENU_GOODBYE: Logs user off and disconnects. FILEMENU_HELP: Displays help file for the files section. FILENENU_EXT: Externally accesses ARC or ZIP file for list/view/dl FILEMENU_READ: Allows user to read any ASCII text file. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM BBS (r) system for OS/2 Page 1-25 Configuring MAGNUM FILEMENU_CHANGE: Allows user to change any file s/he uploaded. FILEMENU_MAKELIST: Allows user to make an ARC'd or ZIP'd file listing of available files by sections desired and dates. FILEMENU_OPT1: Displays file FILEOPT1.BBS from DISPLAY DIRectory. FILEMENU_OPT2: Displays file FILEOPT2.BBS from DISPLAY DIRectory. FILEMENU_BASE: Change FileBase. Requires 'Extended FileBase' module FILEMENU_UTILS: Utilities. Lets users Mark files, unmark, view, etc. --- RJE Menu Definition --- RJEMENU_QUIT: Quits RJE section and returns to main menu RJEMENU_STATUS: For checking the status of any RJE jobs user started RJEMENU_LIST: List/Execute RJE menu file (external file you create RJEMENU_DELETE: Kill an RJE job user started RJEMENU_FILES: Lists completed files (created by RJE job) ready for download RJEMENU_SYSOP: For Sysop use only RJEMENU_HELP: Displays help file for RJE section RJEMENU_GOODBYE: Logs user off and disconnects RJEMENU_OPT1: Displays file RJEOPT1.BBS from DISPLAY DIRectory. RJEMENU_OPT2: Displays file RJEOPT2.BBS from DISPLAY DIRectory. --- SYSOP Menu Definition --- SYSMENU_QUIT: Quits Sysop section - returns to main menu SYSMENU_CMD: Calls the OS/2 Command Interpreter (CMD.EXE) SYSMENU_PRINT: Prints the user database (to a file or device) SYSMENU_MSG: Msg Database Area -maintenance/adjustments of msgs SYSMENU_USER: User Database Area -maintenance/adjustments of users SYSMENU_FILE: File Database Area -maintenance/adjustments of files SYSMENU_ACTIVITY: For listing activity logs (listed backwards) or to remotely snoop on another session. SYSMENU_REMOTE: For remotely accessing the Sysop console. SYSMENU_STATS: Shows the status of the databases (user, msg, file, rje), and performs physical deletions of deleted or expired files and messages. Allows packing of message or file databases. SYSMENU_HELP: Displays the help file for the sysop section SYSMENU_GOODBYE: Logs user off and disconnects SYSMENU_OPT1: Displays file SYSOPT1.BBS from DISPLAY DIRectory. SYSMENU_OPT2: Displays file SYSOPT2.BBS from DISPLAY DIRectory. ----------------------------------------------------------------- Now that we've covered the text (source) file comprising the setup of a node, you are ready to "compile" this file with MAGNUM's MAKEMBBS.EXE program. MAKEMBBS scans your source file for errors and converts everything to a usable and readable "record" by MAGNUM BBS. The syntax for MAKEMBBS is: MAKEMBBS X Where X is the node number of your source file. If you entered MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 1-26 MAGNUM BBS (r) system for OS/2 Configuring MAGNUM "MAKEMBBS 1" (without quotes), MAKEMBBS would look for STARTUP.1 and "compile" it. If all goes well, there will be no error messages (warning messages are ok), your STARTUP.1 file will be deleted and a new file - MBBSINIT.1 will be created. DO NOT BE ALARMED that the STARTUP.1 file was deleted! There are good reasons for the deletion but rest assured, you could recreate the file with the following command: MAKEMBBS -1 >STARTUP.1 The minus sign (-) tells MAKEMBBS to recreate the STARTUP file from the MBBSINIT file. The reason for the deletion is so that you don't accidentally recompile the source file which will overwrite the actual record MAGNUM uses - the MBBSINIT file. If you overwrite the file, you will lose the updates MAGNUM makes to the record after every call - such as incrementing the number of calls received for that node, last caller's name, etc. For node 2, simply use the STARTUP.2 file instead, and change the 1's to 2's in the above examples. The same applies for nodes 3 and 4, etc. If you start MAKEMBBS without any parameters, it will "compile" ALL STARTUP.x files it finds into their respective MBBSINIT.* files! * * * NOTE: This distribution includes a setup program (MINSTALL.EXE) which will create a .CMD file to automate the installation process. The MINSTALL.EXE program will create the necessary subdirectories for you, and when you run the resultant .CMD file, all files from the distribution distribution diskette will be copied to the proper subdirectories. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Directory Structure of MAGNUM Page 2-1 Creating Subdirectories Once you've edited and saved the STARTUP.x files, and ran them all with the MAKEMBBS.EXE program (with error-free results), you're ready to run the setup program MINSTALL.EXE to automate your installation. You should be in the subdirectory containing the output of the MAKEMBBS.EXE program (MBBSINIT.x). Start the MINSTALL.EXE program (no command-line parameters are needed) and MINSTALL.EXE will create a .CMD file for every MBBSINIT.x file it finds. For example, if you have a MBBSINIT.1 file, MINSTALL.EXE will create a MNODE1.CMD file. You'll need to run these command files (once each) with the distribution diskette in drive A to complete the installation. *** NOTE: IF ALL OF YOUR NODES WILL BE USING IDENTICAL DIRECTORY STRUCTURES, YOU CAN RUN ANY OF THE MNODEx.CMD FILES SINCE THEY WILL ALL BE IDENTICAL! IMPORTANT: EACH NODE MUST HAVE ITS OWN, UNIQUE WORK_DIR! After the MNODEx.CMD files have been executed, these are the files which belong in the subdirectories (some of the "canned" files have already been placed there by the MNODEx.CMD command files, others will have to be created, others will be generated during runtime): PROGRAM DIRECTORY: MBBS.EXE Main (parent) program for MAGNUM BBS MSESSION.EXE Child program runs user sessions MAKEMBBS.EXE Configuration compiler/disassembler GETFILES.EXE File xfer pgm called by MSESSION.EXE PUTFILES.EXE File xfer pgm called by MSESSION.EXE MBBSEXEC.EXE Magnum BBS executive maintanence pgm RJEMONIT.EXE RJE monitor program (daemon process) KILLPROC.EXE Used internally by Magnum. STOPMBBS.EXE Stops ALL MBBS.EXE and LOCALBBS.EXE programs running on this computer and on your LAN (if LAN is used). STOPRJE.EXE Stops ALL RJEMONIT.EXE programs running on this computer and on your LAN (if LAN is used). MBBSINIT.x (x=node #) STARTUP.x (x=node #) ANNOUNCE.x (x=node #) When a node is in the 'announce only' mode, each time an announcement is sent, Magnum logs this to a file in your PROGRAM DIRectory called ANNOUNCE.LOG MBBS.ACE File containing ACE (Automatic Command Execution) statements (events). ACE.LOG Contains ACE results - updated whenever an ACE command is executed, and when system is started. REMAPDIR.x (x=node #). Used to remap directories for those running additional copies of Magnum on their LAN. NOTMAIL.x For display when node x is in 'mail only' mode. Displayed when a non-mail MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 2-2 Directory Structure of MAGNUM Creating Subdirectories account tries to logon. SESSION DIRECTORY: SPLITKEY.EXE Rebuilds *.KEY files from USER.DAT AMMO.MAG Optional - used for Remote Mail. NOCHANGE.LST Optional - defines unchangeable parameters within the [E]nvironment selection of the main menu. BADNAME.LST List of unallowable logon names BADUPLD.LST List of unallowable upload filenames NOANSCHK.LST List of file extensions NOT to perform an ANSI check on after upload COMPRESS.LST Define external file compression pgms USER.KEY The keyfile used during logons USER.DAT The user database FILE.DAT The file database MSG.DAT The message database RJE.DAT The RJE database UTILIZ.DAT The utilization database (optional) MILC.SUB (Optional). If present, defines characters which are to be replaced (substituted) with other characters. QSECy.BBS | QSECy.SCR y=user security level SECy.BBS | SECy.SCR IDz.BBS | IDz.SCR z=specific user id BULLETIN DIRECTORY: BULLETIN.BBS | BULLETIN.SCR other files may be NEWSLTR.BBS | NEWSLTR.SCR contained here which QUESTION.BBS | QUESTION.SCR are "included" by QUESNEW.BBS | QUESNEW.SCR any of these particular files. MENU DIRECTORY: MAINMENU.BBS | MAINMENU.SCR if any of these FILEMENU.BBS | FILEMENU.SCR files exist, MAGNUM MSGMENU.BBS | MSGMENU.SCR displays the file SYSMENU.BBS | SYSMENU.SCR for the menu RJEMENU.BBS | RJEMENU.SCR of the dynamic menu it builds internally. HELP DIRECTORY: MAINHELP.BBS | MAINHELP.SCR These are the "help" FILEHELP.BBS | FILEHELP.SCR files MAGNUM looks MSGHELP.BBS | MSGHELP.SCR for when a user SYSHELP.BBS | SYSHELP.SCR wants help in the RJEHELP.BBS | RJEHELP.SCR section of the BBS they are in. DISPLAY DIRECTORY: HELLO1.BBS | HELLO1.SCR Displayed after logon HELLO2.BBS | HELLO2.SCR Displayed after logon HELLO3.BBS | HELLO3.SCR Displayed after logon NEWUSER.BBS | NEWUSER.SCR Displayed for new user only BIRTHDAY.BBS | BIRTHDAY.SCR Displayed on user's birthday MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Directory Structure of MAGNUM Page 2-3 Creating Subdirectories GOODBYE.BBS | GOODBYE.SCR Displayed at logoff PRELOG.BBS Displayed before logon LOWBAUD.BBS Displayed if baud too low CLOSED.BBS Displayed if a closed BBS OPEN.BBS Displayed if running an open BBS and new user not found in user database. QUOTES.BBS Displays a quote from here PREUP.BBS | PREUP.SCR Displays prior to upload POSTUP.BBS | POSTUP.SCR Displays after an upload PREDOWN.BBS | PREDOWN.SCR Displays prior to download POSTDOWN.BBS | POSTDOWN.SCR Displays after download UDRATIO.BBS | UDRATIO.SCR (u/l to d/l ratio exceeded) PRELIST.BBS | PRELIST.SCR (pre file-list message) MAINOPT1.BBS | MAINOPT1.SCR Displays from main [1] MAINOPT2.BBS | MAINOPT2.SCR Displays from main [2] FILEOPT1.BBS | FILEOPT1.SCR Displays from file [1] FILEOPT2.BBS | FILEOPT2.SCR Displays from file [2] MSGOPT1.BBS | MSGOPT1.SCR Displays from msg [1] MSGOPT2.BBS | MSGOPT2.SCR Displays from msg [2] RJEOPT1.BBS | RJEOPT1.SCR Displays from rje [1] RJEOPT2.BBS | RJEOPT2.SCR Displays from rje [2] SYSOPT1.BBS | SYSOPT1.SCR Displays from sys [1] SYSOPT2.BBS | SYSOPT2.SCR Displays from sys [2] FDIR_x.BBS | FDIR_x.SCR Displays when user chooses [L]ist command from Files menu, such that if user lists area G for example, FDIR_G.BBS (or FDIR_G.SCR) will display prior to listing the files in area G. FDIR_x.* files are optional and will only display if the matching FDIR_x.* file exists. CAUTION: Avoid using MILC commands which halt the display or ask for user input because user's may wish to capture your MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 2-4 Directory Structure of MAGNUM Creating Subdirectories entire listing while viewing it in a nonstop fashion. EXTERNAL DIRECTORY: ARC2.EXE (Used for creating, viewing, etc of compressed .ARC files) PKZIP2.EXE / PKUNZIP2.EXE (Used for creating, viewing, etc of compressed .ZIP files) ZIPCMT.x (Comments for uploaded .ZIPs) x=node number. When a remote user finishes uploading a new .ZIP file to the BBS, the contents of the file ZIPCMT.x will be added as a comment to the .ZIP file. CHKANSI.EXE (ANSI Escape Sequence Checker) Called by both the message and file section - if this program detects a harmful ANSI escape sequence to redefine keyboard key(s), MAGNUM BBS immediately ends the user's session and locks them out of the system. You can delete or rename this program if you do not wish Magnum to use it (sometime false harmful escape sequences are reproduced by file compression methods such as ZIP, ARC, etc). CHILDREN.BBS | CHILDREN.SCR (menu for external programs) Known as 'doors' on DOS BBS's. The way this works is that upon exit of displaying this file, the variable @Z0 should hold the program name (no path or drive, just program name - the program is expected to be found in the EXTERNAL DIRectory), variable @Z1 should MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Directory Structure of MAGNUM Page 2-5 Creating Subdirectories hold command line arguments to be passed to the child (if any), and @N0 should have it's bits set as follows: 128 64 32 16 8 4 2 1 | | | | | | | | | | | | | | | \-> 1=echo user input to comport | | | | | | | 0=no echo (child handles echo) | | | | | | \----> 1=cooked mode | | | | | | 0=raw mode | | | | | \-------> 1=CR translates to CR/LF pair | | | | | 0=no translation to CR/LF pair | | | | \----------> 1=CR tranlates to LF | | | | 0=no translation to LF | | | \-------------> 1=CR translates to NUL | | | 0=no translation to NUL | | \-----------------> Not used | | \---------------------> 1=Mark the ACTIVITY.x handle as | inheritbale by the child | process. See MILC command @V92 | 0=ACTIVITY.x handle is not | inheritable by the child | process (default). \-------------------------> 1=Mark comport handle as inheritable by the child process. See MILC command @V0. 0=Comport handle is not inheritable by the child process (default). NOTE: For most doors, such as "adventure", the the following statement would be required: @N0=7; This would set bits 1, 2, and 4 on. To compute the value you need for any particular door, add up the bit "field" numbers which have their bits set to 1. For instance, in the above example, bit fields 1, 2 and 4 are each set to 1. Therefore, adding up bit fields (1+2+4) gives a result of 7. If bit fields 16 and 2 were the only ones set, then 16+2 = 18, thus your @N0 assignment would be @N0=18; RJE DIRECTORY: When in the RJE section of the BBS, the [L]ist/Execute menu selection will look for, and MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 2-6 Directory Structure of MAGNUM Creating Subdirectories display the file RJELIST.BBS (or RJELIST.SCR) in the RJE DIRectory. In our sample distribution, the following files have been placed in your RJE directory by the MINSTALL.EXE program: RJELIST.BBS - sample RJE list/execute menu MSGLIST.EXE - sample RJE program MSGLIST.RJE - sample RJE/MILC processing USERMSGS.CMD - sample RJE command file for the MSGLIST samples above. ADDRJE.EXE - adds RJE files to file database. For more info on this program, execute it without any parms. MARKUNRD.MEX - background process to unmark read messages by a given user. MARKUNRD.RJE - starts MARKUNRD.MEX All RJE programs are expected to be found in this subdirectory. MSG DIRECTORY: Where message files go. Any messages which are a description of an available file for download, will have the same filename as the downloadable file. MSG DIRECTORY is the parent subdirectory, and there MUST be 26 subdirectory entries within this directory, named A to Z. (IE: \magnum\msg\a, \magnum\msg\b ... \magnum\msg\z). These 26 subdirectories will be created by the MINSTALL.EXE program. WORK DIRECTORY: Temporary workspace used by Magnum during sessions. CAUTION: WE STRONGLY RECOMMEND A UNIQUE PATHNAME FOR EACH NODE USED IN YOUR BBS!! USERS DIRECTORY: If you allow your users access to MILC commands @Zx and/or @Nx, any messages they create containing the @Zx or @Nx commands which write output will be written to the same filename as the file containing these commands, but placed in this directory. Also, user NotePads will be kept in this directory. SYSOUT DIRECTORY: ACTIVITY.x (x=comport (node) number) Activity Log SYSCHAT.LOG The log of Chat between Sysop<->User GRPCHAT.LOG The log of Group Chat *.R?? ??=com port number (response files) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Directory Structure of MAGNUM Page 2-7 Order of Display Files Although a little premature for this, you will need to know the order of the display files for later: ANNOUNCE.x - displays only if node is used for "announce only" (x=node #) [logs each 'announcement' to ANNOUNCE.LOG in your PROGRAM DIRectory]. LOWBAUD.BBS - displays if user's baud rate is less than sysop's predefined lowest baud rate PRELOG.BBS - displays after making connection at acceptable baud rate. CLOSED.BBS - displays if user not in database and sysop running a closed bbs. OPEN.BBS - displays if user not in database and sysop running an open bbs. QUESNEW.BBS - displays if applicable and is user's 1st call (and an OPEN BBS) NEWUSER.BBS - displays if this is the user's first call (and an OPEN BBS) BIRTHDAY.BBS- displays if user's birthdate matches current date. ID#.BBS - displays if user's ID# matches. QSEC#.BBS - displays if user's security level matches # - once. SEC#.BBS - displays if user's security level matches # - always. HELLO1.BBS - displays if exists. HELLO2.BBS - displays if exists. HELLO3.BBS - displays if exists. BULLETIN.BBS- reported if changed since last logon, but not displayed. NEWSLTR.BBS - reported if changed since last logon, but not displayed. MAINMENU.BBS- if exists. . . QUOTES.BBS - Ending quote from this file is presented at logoff. The quote number sent is equal to: (NUMBER OF TIMES CALLER CALLED) MOD (NUMBER OF QUOTES) GOODBYE.BBS - if exists. This would be a good place to place MILC command @Wx (Wait x miliseconds) in order to give your modem a chance to empty its buffer (send) to the remote modem before finally disconnecting. @W2000 (wait 2 seconds) is usually sufficient. NOTE: Whenever Magnum can't open or display a file, it will send an informational message to the console (if you're snooping on someone): << SYSOP NOTE: File "filename" Not Found >> The remote user will never see this message, it's merely an informational message. You'll see these messages when you log on locally via the console as well. This message does not indicate an error, it merely indicates that the file didn't exist. For example, the HELLOx.BBS files are optional, and this message will display for each one of those files not found - this is normal. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank Running MAGNUM BBS Page 3-1 Starting MAGNUM BBS for the First Time Rather than go into the detail about the various .BBS and .SCR files, you can use the ones supplied for now and tailor them to your own liking later on. This way you can start your BBS now - not after hours of editing the .BBS files. Make sure you are in the subdirectory you've defined for PROGRAM_DIR. You should have at least the following files in that subdirectory: MBBS.EXE MSESSION.EXE MAKEMBBS.EXE GETFILES.EXE PUTFILES.EXE MBBSEXEC.EXE RJEMONIT.EXE STOPMBBS.EXE STOPRJE.EXE KILLPROC.EXE MBBSINIT.? (?=node#) IMPORTANT: ---> Just a reminder that this document assumes the 4-node version of Magnum, in which case node 4 (ie: STARTUP.4 and MBBSINIT.4) comprise your local console node. If you have the 2-node version, node 2 is your local console node. If you have the 9-node version, node 9 is your local console node. If you have the 17-node version, node 17 is your local console node, etc! If you have a PS/2, the COM02.SYS device driver will support up to 3 communications ports, otherwise the COM01.SYS device driver (for AT class machines) will support 2 communications ports. MAGNUM is currently compiled to support the limit of COM02.SYS or 3 ports, therefore COM4 (a virtual node) reserved for local (modemless) logon by the sysop will be the local node. You will need to create a STARTUP.4 file and use MAKEMBBS.EXE to compile the file into an MBBSINIT.4 - To do this simply copy one of your other STARTUP.x files and modify the node number in the file to reflect comport 4. This file will be used for local (console, modemless) logons. Don't worry about what's in the modem startup strings or other parameters - they will be ignored at startup, however, something *is* necessary in these fields, so this is why I suggest to simply copy the file from startup.1 or startup.2 and modify the comport number. Simply compile with MAKEMBBS.EXE and you're set to do your first, local (modemless) logon! NOTES: Prior to starting your BBS, you should modify your PATH statement to include your PROGRAM_DIRectory, EXTERNAL_DIRectory, and your RJE_DIRectory paths. It might also be a good idea for you to create a .CMD file to set these paths and to start MBBS.EXE automatically (from the system STARTUP.CMD file) in the event of a power failure - this way, the system will restart when the power returns. Magnum only opens comports provided both the following criteria MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 3-2 Running MAGNUM BBS Starting MAGNUM BBS for the First Time are met: 1) An MBBSINIT.x file exists for comport x, and 2) the MBBSINIT.x file was "compiled" with the ACTIVE parm set to Y. If either of these cases is false, the comport will not be used and will be available for all other programs wishing to open the particular comport. At this point you can start MAGNUM by entering MBBS on the command line. Any MBBSINIT file found by MAGNUM with the ACTIVE parm set to Y will result in MAGNUM opening the comport for that node and sending the initialization strings to the modem. Any MBBSINIT file with the ACTIVE parm set to N (and any MBBSINIT file NOT found) will result in Magnum not using the comport for those particular node(s) and will leave those comports free to be used by other programs. After initialization, you will do a local logon by typing the following: * LOGON Shortly after you hit the '*' character, it will appear next to the "Command=>" prompt. To start a command, you either need to start with the '*' character or the node number. In the case of local logon, you need to start with the '*' character. Before you hit the '*' character, MAGNUM was checking the comports for incoming calls. Once you hit the '*' or node number (1, 2, etc) - MAGNUM immediately stops checking for incoming calls and accepts what you have to type at the "Command=>" prompt. MAGNUM always assumes that if you're typing something at the "Command=>" prompt that it's of very high priority, so it stops what it's doing (checking for incoming calls) until you've entered a command and it finishes processing that command. The syntax of commands are always "X COMMAND" where X is an asterisk or digit - remember to always leave one space between the X and the COMMAND. After you've entered the "* LOGON" command, MAGNUM will call MSESSION.EXE to run your session. You are a new user at this point since there is no entry in the user database for you (or anyone else for that matter). Once you are prompted with the "LOGIN" prompt, enter your First Name exactly the way it appeared in your config file and press enter. Do the same with middlename and lastname - these must match the config file exactly! Once it matches, MAGNUM will welcome you as Sysop and make you go through the "new user logon procedure". If per chance someone has called your BBS prior to you logging on for the first time, they will get a "system not initialized" message and be automatically logged off. You (as sysop) must have an ID number of /0 (read as slash-zero). After you complete the new user logon procedure, you can now go into the sysop section and modify your parameters to whatever parms you wish. Once in the sysop section, choose the User area. Your profile should come up on the screen. Simply enter any fieldname you wish to change and hit enter - MAGNUM will then prompt you for the new value of that field. Everything else in the user area of the sysop section is self explanatory but we'll go into more detail on that later on. IMPORTANT: When online locally, the up and down arrow keys, and the PgUp MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Running MAGNUM BBS Page 3-3 Starting MAGNUM BBS for the First Time and PgDn keys have special meaning. These keys are accepted at any prompt, and you should use extreme caution with these keys, as they change the priority of your local session. Anytime you're looged onto the local console, you can increase/decrease the priority of your local session with the following keys: PgUp - Increases Priority Class by 1 PgDn - Decreases Priority Class by 1 UpArrow - Increases Priority Level (within a class) by 1 DownArrow - Decreases Priority Level (within a class) by 1 These keys are recognized at any system prompt, but will not be recognized during message entry or chat modes. CAUTION: Setting your priority too high can cause other online sessions to "freeze" and file xfers on other sessions to "time out" (fail)! Try avoiding Class 3 altogether! There are 3 Priority Classes (1-3), the higher the class, the higher the priority. Within each class, there are 32 levels (0-31), the higher the level, the higher the priority within that class. Class 1 is "Idle Time", Class 2 is "Regular", and Class 3 is "Time Critical". Remote users are running in Class 2. The local logon is started as class 1, level 31 because when running locally, OS/2 gives a boost to the foreground session. Keep in mind that since you'll be running your local logon in the foreground, the higher the priority you give to your session, the slower the remote sessions will become because OS/2 is granting more processing time to your local session. After pressing any of the above 4 keys, Magnum will display an informational message similar to the following: Priority: Class=1, Level=31 Although this informational display sort of "messes up" the nice system prompt from where you were at, the prompt is unaware of any changes and still expects normal input as though nothing had happened. If you press any of the 4 keys too many times in succession, the informational messages sent with each keypress can cause the original prompt to scroll off the screen, so remember where you left off! This will become clearer to you as you use these realtime priority setting keys. IMPORTANT: In the LOCAL session, Class 2 Level 0 (just one notch above the default of Class 1 Level 31) will cause any remote users to notice significant slowdown! You should NEVER go above Class 2 Level 0 unless you are the only one on the system and you are running some other cpu-intensive application that you want higher priority over. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 3-4 Running MAGNUM BBS Starting Your FILES Database Now that you're on the system, it is ready for use by others! One of the first things that a sysop usually does is to add files to the file section. There are several ways to do this: 1) Upload them via remote modem/computer; 2) Manually place the files into the proper subdirectories you've set up and then use the Sysop section (file maintenance) to add them; 3) If you're logged on locally, go into the [F]ile section and choose [U]pload - as long as you've logged on locally (from the Console), the actual file transfer (no matter which one you choose) will prompt you for the source of the file and will perform a local "copy" of the file. For example, if you had a file on diskette in drive A and wanted to get it into the files database, supply the name of the file (drive, path, etc) and Magnum will copy it from drive A to the proper subdirectory - this simulates an upload. 4) if you are converting from another BBS system, and you know the record layout of its file database, you may be able to write a conversion program. We supply the layout of our databases in a file entitled MAGNUM.H located on your distribution diskette. MAGNUM allows an optional message to be associated with each file. This optional message can be up to 150 lines of text in length. Other than doing an upload from a remote computer, MAGNUM will let you create or modify any message for a file through the file menu's "[C]hange" command. On uploads of files in .ZIP format (a popular compression method used by PKWare), you can add a customized "zip file comment" to all uploads. See Chapter 2 (EXTERNAL DIRECTORY) for more information. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-1 Intro The end of Chapter 2 lists the order of display files. This chapter will explain the embedded MILC (Magnum Interpreted Language Commands) which can be a part of each of your display files. MILC is a very powerful BBS language. Before we go into that, it should be pointed out that anytime MAGNUM displays a file, it first looks to see if the user who's going to view the file has their color settings on. If yes, it looks for whatever filename that's about to be displayed with an extension of .SCR - if it finds it, it displays it - otherwise, it displays the filename with an extension of .BBS instead. Files with an extension of .SCR are meant for color users only - you needn't have any .SCR files to have color, but basically your .SCR files are the ones with the fancy ANSI escape sequences in them to do things like motion, cursor positioning, etc. Whether you use .SCR files or not, MAGNUM has provided a way for you to use color in your .BBS files and present the color sequences to those using color, or ignore them for those not using color - all transparent to the user viewing the files. MAGNUM's MILC language lets you take advantage of advanced display techniques such as mathematics, string logic, IF, inclusion of other files (with options), branch to anywhere in the file, perform I/O, screen control (including color), give the illusion of a customized display to the current user, and multitudes more! Embedded MILC commands in Display Files Display files typically have extensions of .BBS or .SCR and display on the remote user's terminal. The difference between .SCR and .BBS files is .SCR files are searched for and displayed ONLY if the remote user has his color setting set to YES. In the event that a .SCR file is not found, the corresponding .BBS file is displayed instead. .BBS files may also contain color, however, the color is via embedded MILC color commands which are executed only if the remote user has his color setting set to YES, otherwise the embedded color commands are ignored. Display files are not limited to .SCR or .BBS files. Every message (mail) entered on your system in the message section can also contain MILC commands (refer to the page #'s defining the DISP_CMDS field in the index). The DISP_CMDS field of each user's record defines which of the MILC commands are available for them to use in their messages. In the case of MILC commands appearing in messages, the commands which the originator of the message are allowed to use (not the reader) are governed by the originator's DISP_CMDS field. All display files (except PRELOG.bbs, LOWBAUD.bbs, CLOSED.bbs and OPEN.bbs) may contain embedded MILC commands. Numerous categories of commands exist, each beginning with the command character "@" (without the quotes). The above named exceptions may contain MILC commands which do NOT reference any USER-specific information because the user is not fully logged on at this time (ie: Magnum has no way of knowing their name or any other information about the user). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-2 Customizing MAGNUM - Display Files/MILC Commands Color Commands (@A) @A commands PURPOSE: Change colors for 'color users' -no effect on 'non-color users' FORMAT: @Ax Where 'x' is a 1 to 3 digit number ranging from 0 to 255. The @A commands are the ones that change the color attributes. Once a @A command is executed, that color will remain until the end of the file or until another @A command is executed. The following are the attribute values of 'x': @A0 - BLACK on BLACK @A8 - GRAY on BLACK @A1 - BLUE on BLACK @A9 - hi-intensity BLUE on BLACK @A2 - GREEN on BLACK @A10 - hi-intensity GREEN on BLACK @A3 - CYAN on BLACK @A11 - hi-intensity CYAN on BLACK @A4 - RED on BLACK @A12 - hi-intensity RED on BLACK @A5 - MAGENTA on BLACK @A13 - hi-intensity MAGENTA on BLACK @A6 - BROWN on BLACK @A14 - bright YELLOW on BLACK @A7 - WHITE on BLACK @A15 - hi-intensity WHITE on BLACK @A16 to @A31 - same as @A0 to @A15 but on BLUE background @A32 to @A47 - same as @A0 to @A15 but on GREEN background @A48 to @A63 - same as @A0 to @A15 but on CYAN background @A64 to @A79 - same as @A0 to @A15 but on RED background @A80 to @A95 - same as @A0 to @A15 but on MAGENTA background @A96 to @A111 - same as @A0 to @A15 but on BROWN background @A112 to @A127 - same as @A0 to @A15 but on WHITE background @A128 to @A255 - same as @A0 to @A127 but blinking (simply add 128 to any of the above for blinking) Example: @A2 You are a @A10New User@A2 and we welcome you aboard! this would print: "You are a New User and we welcome you aboard!" where then entire sentence is displayed in green except for "New User" which is displayed in hi-intensity green. If the remote user had his color settings set to NO, then the sentence would appear normally and all in one color (whatever color his CRT displays, and the @Ax commands are automatically removed). Notes: As with all '@' commands, the @Ax commands will not be displayed, but their effects will be displayed. The @A commands will have no effect if the user viewing any text containing these commands has their 'color' selection turned off - they will simply be stripped from the text and not executed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-3 Branch (IF) Commands (@B) @B Commands PURPOSE: Branch conditionally or unconditionally to another part of the file FORMAT: @Bx(EXP); where 'x' is the label number to branch to (0 to 99), and EXP is the expression to be evaluated. If EXP (expression) is TRUE, the branch is taken, otherwise display continues. The @B command alters the display of a file. It can jump forward, backward, or not at all depending on the expression in parenthesis. NOTE: Please read about the @Z, @N, and @P commands and have a thorough understanding of them before attempting to read further. In order for a branch to take place, the following 2 conditions must be met: 1) The expression must be TRUE 2) The label must exist somewhere in the current file Let's say you have defined a label somewhere in your file as label # 5 (an embedded @P5 somewhere in the file). The label could be in a previous part of the file or in a forward part of the file (ie: anyplace). Since this is best learned by examples, lets start with a forced (unconditional) branch: @B5(0=0); [ NOTE: @B5; is identical to @B5(0=0); ] This would cause an unconditional branch to label 5 (@P5) since the expression (0=0) is true. The "=" sign means to compare the left parameter with the right parameter and if they are equal, the result is true. If the expression were (0=1) instead, then no branch would take place since 0 does not equal 1. This is the simplest of the branch instruction. The valid comparators are: = equal to > greater than < less than >= greater than or equal to <= less than or equal to != not equal to ~ If string2 is contained within string1 !~ If string2 NOT contained within string1 Using numeric variables (see the @N command), let's try a few more examples: @B5(N2=16); @B5(N2!=N12); MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-4 Customizing MAGNUM - Display Files/MILC Commands Branch (IF) Commands (@B) @B5(N4<N2); Note in all three examples the absence of any spaces. All branch commands MUST BE TERMINATED WITH THE ';' character (semicolon)! Using string variables (see the @Z command), let's try a few more examples: @B5(Z3=Z4); @B6(Z2!="John"); Note the use of Quotes to define a "hard-coded" string (as opposed to a variable string). The "hard-coded" string may contain embedded spaces within the surrounding quotes. NOTE: string comparisons are NOT case sensitive. This means that "John" is the same as "joHN". Now for a working example: @N1=0; This line is being displayed @P5 This line will be displayed twice @N1=(N1+1); @B5(N1=1); And now on to the next line Evaluating the above, the first @ command is @N1=0; which assigns 0 to the variable N1. The text "This line is being displayed" is displayed. Next, a label (@P5) is defined and the text "This line will be displayed twice" is displayed. After that, an arithmetic expression that increments variable N1 by 1 is encountered. N1 is increased by 1 and now contains the value 1. The branch command says to branch to label 5 (@P5) if N1 is equal to 1. Since the expression is TRUE, a branch is taken to @P5 and "This line will be displayed twice" is displayed again. N1 is again incremented by 1, leaving the value 2 in variable N1 as a result. The branch statement becomes false (N1 is now equal to 2, not 1) and the display continues with "And now on to the next line". To check if a string is contained within another string, lets suppose that the variable @Z1 contained "HAPPY NEW YEAR". If you wanted to check to see if "EAR" were contained within the string, you could do it as follows: @B5(Z1~"EAR"); EAR is not in @Z1; @P5 What this would do is check if string2 ("EAR") were contained in string1. If the result is TRUE, a branch would be taken to label @P5, otherwise no branch would be taken and processing would continue with displaying "EAR is not in HAPPY NEW YEAR". However, in this case, the comparision is TRUE and the branch would be taken to @P5, skipping over the display of "EAR is not in HAPPY NEW YEAR". NOTE: A forced (conditional) branch does not need the (EXP) part of the statement. For example, @B5; and @B5(0=0); are identical. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-5 Screen Control Commands (@C) @C Commands PURPOSE: Controls the screen/display FORMAT: @Cx where x is a numeric parm representing the control function The @C command controls the screen or display of a file. The parameters are 0 through 11 as follows: @C0 - NONSTOP. This is the same effect as the remote user answering 'N' to the "-- MORE -- [C]ont, [S]top, [N]onstop" prompt. @C1 - STOP, WAIT FOR KEYPRESS. This command stops the display and waits for the remote user to strike a key. Note that no prompt is given - you should supply your own prompt to let the remote user know that you are waiting for them to press a key. (ie: "Press any key ...@C1") @C2 - RESUME NORMAL DISPLAY. This command negates the @C0 command - it resumes normal prompting ("-- MORE --") when a full screen is displayed (and the remote user has their "MORE" prompts turned on). @C3 - BEGIN SKIP. This command is kind of like a comment that never gets shown. Everything following this command is skipped until a @C4 command is encountered. @C4 - END SKIP. This command negates the @C3 command. Normal Display and processing of text and commands resume when this command is encountered. @C5 - IGNORE COMMANDS. Similar to the BEGIN SKIP (@C3) command, this command turns off, or disables command processing. All commands that follow from this point on will be treated as text instead of commands (and thus displayed instead of processed). The @C6 command is the exception, which negates this command. @C6 - PROCESS COMMANDS. Negates @C5 command. When @C6 command is encountered, normal command processing will resume. @C7x - CHANGE COMMAND CHARACTER. This is the only command in the @C group of commands that takes another parameter. That parameter is a single character which tells the file display routines to use a different character to recognize commands with. For example, the command @C7% tells the file display functions that the '%' character is now the command character, not the '@' character. So, @C7^ makes the '^' character the command character from that point on, until another ^C7 command is issued to change it to another character. Use extreme caution in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-6 Customizing MAGNUM - Display Files/MILC Commands Screen Control Commands (@C) selecting a command character - that character should only be used for commands and not text. @C8 - RESET LINECOUNT. This command resets the line counter used for the -More- prompt. This comes in handy after 'including' a file or branching to somewhere in the file where this would become necessary. @C9 - PRESS ENTER. This command prompts the remote user to press their ENTER (or C/R) key. The file display stops, the "PRESS ENTER ..." prompt appears, and the function waits until the remote user presses ENTER. @C10 - BREAK OFF. This command turns off the ability to break or stop display of a file with the <Ctrl-X> or the space bar. Although this command can appear anywhere in the file, a user can still stop the display if s/he does so before this command is processed. However, if @C10 is contained as the first 4 characters of the file, the command is guaranteed to take affect because Magnum will disallow a break during the first 4 characters of a file for this purpose. @C11 - BREAK ON. This command negates the @C10 command. @C12 - Ignore all text - process commands only. Ideal for large blocks of commands where CR/LF and spaces are not intended to display. Stays in this state until @C13 encountered. ** CAUTION: Be careful when using @B (branch) commands without issuing a @C13 to turn text display/processing back on again. @C13 - Negate @C12. @C14 - Turn off HIGHLIGHT. Ordinarily, reader display of @Z, @N, @O, and @U substitutions are highlighted. The @C14 command turns off this highlighting. NOTE: highlight is only active when the remote user's color setting is Y. @C15 - Negate @C14. @C16 - Terminate display of current file. @C17 - Log the user off! (be careful with this one!) Emulates a dropped carrier (disconnect). Sysop/Cosysop use only! @C18 - Clears the screen. If the user's color settings are set to YES, an ANSI "clear screen" escape sequence is sent, otherwise a FormFeed character (Ctrl-L) is sent. @C19 - forces an internal result code of FALSE (ie: file not found or file not displayed). An example of the use for MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-7 Screen Control Commands (@C) this command would be the following: You wish to display something using your external menu(s) (ie: FILEMENU.BBS, MSGMENU.BBS, etc), but also want Magnum to dynamically generate the menu. Magnum only generates an internally-built dynamic menu if the xxxxMENU.BBS (or xxxxMENU.SCR) file doesn't exist. Within this file, you can now issue the @C19 command, which will generate an internal result code indicating that the file was not found - even though the file is displayed. This essentially "fools" the menu routines into thinking that the menu file was not found and will therefore generate the internal menu. This MILC command is ignored if it appears within a message file. This MILC command does not terminate the display of a file, it merely sets the internal result code. NOTE: The external menu file is only displayed upon entrance to the menu. After that, the internal menu will be dynamically generated each time the menu needs re-generation. If the menu is exited, then returned to (ie: if in FILE menu, then the menu will be re-generated if they choose [Q]uit, and then re-enter the FILE section anytime afterward). @C20 - Make the length of the string variable in @Z0 equal to the length of the variable in @N0. The following gets the user's first name into variable @z0, makes the length exactly 10 characters, then displays it: @z0=u3; @n0=10; @c20; @z0; MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-8 Customizing MAGNUM - Display Files/MILC Commands Date Conversion Function (@D) @D Command PURPOSE: Converts a partial date to a 10-character date string (MM/DD/YYYY or DD.MM.YYYY depending on user's date format). FORMAT: @Dx When prompting a user for a date, they may enter a date in a format such as M/D, MM/D, M/DD, MM/DD, MM/DD/Y, MM/DD/YY, etc (or it's European equivalent entry). The @Dx command simply converts a partial date to a 10-character date string. The 'x' tells the @D command which @Zx variable holds the partial date string. In the following example: Enter Starting Date => @Z5(10); @D5 The @Z5(10); prompts the user for a string of up to 10 characters which will be placed in variable @Z5. The @D5 command converts the date in variable @Z5 to a 10-character date string. For example, if the user entered "3/1" in response to the date prompt, the @D5 statement would convert the string to "03/01/1990" (or whatever the CURRENT YEAR happens to be). If the user has specified European date formats in their Environment settings, the date would be converted to 01.03.1990 instead. In the event a user enters garbage in response to the prompt (ie: an invalid date or invalid partial date), the @Dx function will convert the string in @Zx to "01/01/1980" (or 01.01.1980). Users can enter dates in either MM/DD/YYYY or DD.MM.YYYY formats. If the conversion routine called by @Dx sees the '/' character, it assumes the date has been entered in US date format, otherwise if it sees the '.' character, it assumes the date has been entered in European date format. If the user entered the date in US format but had their default settings to European, the date in @Zx would also be converted to European date format. Likewise, if the user entered the date in European format but had their default settings to US, the date in @Zx would also be converted to US date format. As a result, any external programs you write which accept a 10-character date as input, must also be able to accept the date in either US or European format. Conversion from one format to another is not very difficult at all if the date is always supplied as a 10-character string. For example, in the 'C' language, the following functions would perform your conversions: date2US(datestring) /* Converts from European or US date */ char *datestring; /* format to US */ { char c; if(datestring[2]=='/') /* Already in US format - return */ return; if(datestring[2]=='.') /* If in European format, do conversion */ { c=datestring[0]; datestring[0]=datestring[3]; MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-9 Date Conversion Function (@D) datestring[3]=c; c=datestring[1]; datestring[1]=datestring[4]; datestring[4]=c; datestring[2]=datestring[5]='/'; } } date2European(datestring) /* Converts European or US to European */ char *datestring; { char c; if(datestring[2]=='.') /* Already in European format - return */ return; if(datestring[2]=='/') /* If in US format, do conversion */ { c=datestring[0]; datestring[0]=datestring[3]; datestring[3]=c; c=datestring[1]; datestring[1]=datestring[4]; datestring[4]=c; datestring[2]=datestring[5]='.'; } } These routines are only examples, but are very fast because there's no function calls made and all we're doing is manipulating characters! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-10 Customizing MAGNUM - Display Files/MILC Commands External and RJE Program Execution Commands (@E) @E Command PURPOSE: Starts an External (child process or door), or RJE (independent process) program. FORMAT: @Ex @E0: @E0 - Executes an external program (without using the [D]oor menu). Works the same as [D]oors (child processes) - the external process being called must be in the EXTernal DIRectory. The variable @Z0 holds the program name, @Z1 holds any parameters needed by the program, @N0 tells how the pgm's I/O is to be handled. When the external program finishes executing, the result code of the program will be placed in MILC variable @N1. See CHILDREN.BBS in the "Creating Subdirectories" portion of the user's manual. See Chapter 2, CHILDREN.BBS of EXTERNAL DIRectory for more information. CAUTION: DO NOT ALLOW YOUR USERS ACCESS TO THIS COMMAND!! MAKE SURE IT DOES NOT APPEAR IN THE "DISP_CMDS=" OF ANY USER'S RECORD!! IF A USER HAS ACCESS TO THIS COMMAND, THEY COULD TAKE CONTROL OF YOUR ENTIRE SYSTEM AND DO ANYTHING THEY WANT!! @E1: @E1 - Similar to MILC variable @E0, except the process is started as an RJE task (detached and running in the background), and is expected to be found in your RJE DIRectory. The process must NOT read from stdin, or write to stdout or stderr (it actually can write to stdout/stderr but output will be lost!), and must NOT require any keyboard or mouse input or screen output (redirection of stdin, stdout and stderr is ok), otherwise all I/O should be to and from FILES only, not devices! If the print spooler is enabled, this is probably ok. As with the MILC @E0 command, the required @Z0 and @Z1 parameters are the same, but the @N0 and @N1 parameters are different: @N0 should contain the Priority CLASS and LEVEL of the process: NO CHANGE IN CLASS: 1 = lowest priority level of the class 31 = highest priority level of the class CLASS 1 (Idle Time) 100 = lowest priority level of "Idle" Class (class 1, level 0) 131 = highest priority level of "Idle" Class (class 1, level 31) CLASS 2 (Regular) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-11 External and RJE Program Execution Commands (@E) 200 = lowest priority lvl of "Regular" Class (class 2, lvl 0) 231 = highest priority lvl of "Regular" Class (class 2, lvl 31) CLASS 3 (Time Critical) 300 = lowest priority lvl of "Critical" Class (class 3, lvl 0) 331 = highest priority lvl of "Critical" Class (class 3, lvl 31) For example, if you want your RJE program to run in the "Idle Time" class, with a priority level of 15 (the middle of the class), you would assign the value of 115 to variable @N1 as follows: @N0=115; If you don't want to bother with setting priority levels, simply assign an invalid number to variable @N0 (ie: @N0=99;), which will force Magnum to assume a default of 125 (class 1, level 25). Valid numbers are: 1 to 31, 100 to 131, 200 to 231, and 300 to 331. The contents of MILC variable @N1 tells Magnum whether to notify the user in the event the RJE job completes while they're still online. If @N1 is zero, no notification will take place, otherwise if @N1 is 1 (nonzero), Magnum will notify the user of the completed RJE job in the event that the job completes before the user's session is over. Once the process has been started, the values in MILC variables @Z1 and @N1 will be overwritten with information about the RJE process. Variable @Z1 will contain a 10-character string which is the name Magnum assigns to the job, and variable @N1 will contain the process's PID (Process Identification as used by OS/2). If the PID (@N1) contains the value of 0 after starting the job, then this indicates that the job was unable to be started, otherwise if non-zero, the job started successfully. NOTES ABOUT @Ex COMMANDS: In many cases, you'll want (or need) to run a .CMD file instead of a single .EXE program. In order to run .CMD files, you need to specify CMD.EXE as the program to run, and give it a parameter of "/c xxxxxxxx.cmd" (where 'xxxxxxxx' is the name of your .CMD file. For example, if you wanted to run a .CMD file called RUN.CMD, your @Zx MILC commands would be set up as follows: @z0="cmd.exe"; @z1="/c run.cmd"; Of course, you could also have supplied parameters to pass to the .CMD file as well: @z0="cmd.exe"; @z1="/c run.cmd parm1 parm2"; It's important to remember the "/c " as the first thing in the @z1 string because it tells OS/2 to terminate the "cmd.exe" program MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-12 Customizing MAGNUM - Display Files/MILC Commands External and RJE Program Execution Commands (@E) when your .CMD file finishes executing. *** IMPORTANT: IF YOU DON'T SUPPLY THE "/c " PARAMETER AS THE FIRST THING IN @Z1 WHEN "CMD.EXE" IS THE PROGRAM IN @Z0, THEN CMD.EXE WILL NOT END!!! THE REMOTE USER WILL HAVE THE CMD.EXE COMMAND PROMPT (AND YOUR ENTIRE SYSTEM) AVAILABLE FOR THEM TO DO WHATEVER THEY WANT! CAUTION: DO NOT ALLOW YOUR USERS ACCESS TO @Ex COMMANDS!! MAKE SURE E DOES NOT APPEAR IN THE "DISP_CMDS=" OF ANY USER'S RECORD!! IF A USER HAS ACCESS TO THIS COMMAND, THEY COULD TAKE CONTROL OF YOUR ENTIRE SYSTEM AND DO ANYTHING THEY WANT!! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-13 Miscellaneous @E commands Miscellaneous @E commands PURPOSE: To perform certain functions which should only be available to the Sysop. FORMAT: @Ex @E2 - Send File. This command transmits a file that is NOT in the file database to the remote caller. @Z0 holds the filename. Upon return of the transmission, variable @N0 holds the result (1=success, 0=failure). If the user does not have a default file xfer protocol chosen, s/he will be prompted for one. The function also determines whether the caller is on remotely, locally or via pipe module and acts accordingly. This function provides a means of file xfer unrelated to the BBS. No upload/download ratios are checked, remaining time is not checked, the file is not counted as a download, etc. Example: @Z0="d:\magnum\somefile.zip"; @E2 @B1(N0=1); File Transmission Unsuccessful! @C16 @P1 File Transmission Successful! For those Sysops who wish to "attach" a file to a message, this command will let you accomplish it. @E3 - Receive File. This command receives a file from the remote caller and does NOT update the file database. @Z0 holds the filename. Upon return of the function, variable @N0 holds the result (1=success, 0=failure). If the user does not have a default file xfer protocol chosen, s/he will be prompted for one. Note that if the file exists, the function will delete the file prior to receiving it. The function also deletes the file if the file transfer fails. The function also determines whether the caller is on remotely, locally or via pipe module and acts accordingly. This function provides a means of file xfer unrelated to the BBS. No upload credit is given, remaining time is not checked, the file is not integrity checked, upload/download ratio not adjusted, etc. Example: @Z0="d:\magnum\somefile.zip"; @E3 @B1(N0=1); File Reception Unsuccessful! @C16 @P1 File Received Successfully! @E10 - Disable output. Suspend all output to modem or screen. All output sent following this command will be discarded (ignored) until the @E11 command is issued. @E11 - Enable output. Negates @E10, resumes output. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-14 Customizing MAGNUM - Display Files/MILC Commands Miscellaneous @E commands @E12 - Disable Timer. This command comes in handy when someone is about to run out of time on your system, and you want them to have more time. For example, suppose you run a subscription service or offer an 'online order' menu in which users can place credit card orders. We've seen users get logged off by Magnum because they ran out of time, yet they were in the middle of trying to place on online order! When you use the new @E12 command, this will no longer happen. The timer is temporarily suspended with this command, until you issue an @E13 command to reactivate the timer. NOTE: If you forget to negate this command with the @E13 command, the timer will not reactivate! Therefore, we've built in a safety measure. If you use this command, Magnum will automatically issue an @E13 command internally after a period of 5 minutes. @E13 - Enable Timer. Negates @E12 (ie: re-activates timer). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-15 Additional @E commands for 'Extended FileBase and MsgBase' Additional @E commands for 'Extended FileBase and MsgBase' PURPOSE: To provide processing power for those Sysops using optional 'Extended FileBase' and/or 'Extended MessageBase' modules. FORMAT: @Ex @E80 - Prompts User to choose new FileBase (0-255). New FileBase chosen is also returned in @N0;. Requires 'Extended FileBase'. @E81 - Changes FileBase to value (0-255) in @N1;. New FileBase is also returned in @N0;. At the end of the @E81 command, if variables @N0 and @N1 are equal, no change took place. Requires 'Extended FileBase'. @E82 - Prompts User to choose new MsgBase (0-255). New MsgBase chosen is also returned in @N0;. Requires 'Extended MsgBase'. NOTE: This command is ignored if part of a Message! @E83 - Changes MsgBase to value (0-255) in @N1;. New MsgBase is also returned in @N0;. At the end of the @E83 command, if variables @N0 and @N1 are equal, no change took place. Requires 'Extended MsgBase'. NOTE: This command is ignored if part of a Message! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-16 Customizing MAGNUM - Display Files/MILC Commands Include File Commands (@I) @I Command PURPOSE: Includes (displays/processes) another display file within the current display file. FORMAT: @Ix"d:\path\filespec" | @Ix@Zy The INCLUDE command simply halts display of the currently displaying file, processes the 'included' file (and any 'included' files it may have), then returns to either continue displaying the current file or ending the display of the current file, depending on parameter 'x'. 'x' can be one of 0 to 4: 0 = Terminate the current file after the include. Inheritance OFF. 1 = Continue the current file after the include. Inheritance OFF. 2 = Terminate the current file after the include. Inheritance ON. 3 = Continue the current file after the include. Inheritance ON. 4 = Same as 3 but the alterations to @Zx and @Nx variables by the 'included' file will remain upon return. Inheritance OFF means that the included file will have its own @Nx (numeric) and @Zx (string) variables. Inheritance ON means that the included file will inherit the @Nx and @Zx variables of the calling file - upon return to the calling file, the @Nx and @Zx variables will be restored to where they were prior to the 'include' if 'x' was 3, otherwise if 'x' was 4, the @Nx and @Zx variables will retain any changes made by the 'included' file. NOTE: Please have a thorough understanding of the @N and @Z commands before continuing! This powerful command is the entire basis for Bulletins, Questionairres, Newsletters or any other kind of file offering a menu. An example Bulletin file (BULLETIN.BBS or BULLETIN.SCR) might look something like this: @P30 @c8 @a14BULLETIN MAIN MENU@a10 1 - What is MAGNUM BBS and who is Gilmore Systems, anyway? 2 - WOW! How can I get a copy of MAGNUM, What's the price? 3 - Info about becoming a purchasing MAGNUM BBS software. Q - Quit - return to BBS Choice => @z0('123Q'); @b1(z0="Q"); @z1=("c:\gs\com\1\bul_dir\bullet"+z0); @i1@z1 @b30(0=0); @P1 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-17 Include File Commands (@I) The file works like this: The @P30 defines a label. The @C8 resets the line counter (for the -More- prompt). The @A14 and @A10 commands change the color. All text is displayed. After "Choice => " is displayed, the @Z0 command restricts the user to choose one of 1,2,3 or Q. If the user chose Q, a branch is made to @P1 which is the end of the file. Otherwise, no branch is made and string variable @Z1 is assigned a partial filespec to which the user's choice ("1", "2", or "3") is concatenated (if the user chose "2" for example, @Z1 would contain "C:\GS\COM\1\BUL_DIR\BULLET2"). The next command 'includes' the file named in variable @Z1 without inheritance and continues with the next instruction after the 'included' file is finished displaying. The next instruction unconditionally branches to label @P30 to start the whole process over again. The above example used a @Zx (string) variable to contain the name of the file to be 'included'. Note that for less sophisticated menus, you could 'hard-code' the filename within quotes: @I0"c:\gs\com\1\bul_dir\bullet2" or @I0"c:\gs\com\1\bul_dir\bullet2.bbs". NOTES: 1) The variable @Z1 purposely was not given a filename extension. When no filename extension is given, the 'include' command will first look for the filename with an extension of ".SCR" if the user's color settings are set to YES. If not found, or if the user's color settings are set to NO, then it will look for the filename with an extension of ".BBS". If neither is found, the 'include' ends, returning back to the calling file. 2) DO NOT go beyond 3 to 4 levels of includes. In other words, for maximum safety, File A can include file B, which includes file C, which includes file D. Do not go beyond this point to a file E! 3) Note that unlike other '@' commands, when a @Zx variable contains the name of an 'included' file, the '@' (or current command character) is needed. In other words, @I1@Z4 is correct, while @I1Z4 is incorrect. With the power of the @I command, menus and submenus can be built to form a sophisticated Bulletin menu/system, Questionairre menu/system or Newsletter menu/system. When a caller logs on, the system will check to see if either BULLETIN.SCR (or BULLETIN.BBS), and NEWSLTR.SCR (or NEWSLTR.BBS) has a filedate later than the caller's last call. If true, the system will advise the caller that BULLETIN(s) or NEWSLETTER(s) have been updated since their last call (giving dates and times of updates). So remember that if you make a change to any of the 'included' files, you must change the date of the BULLETIN.SCR (or BULLETIN.BBS), or NEWSLTR.SCR (or NEWSLTR.BBS). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-18 Customizing MAGNUM - Display Files/MILC Commands Date Manipulation Commands (@J and @Y) @J and @Y Commands PURPOSE: Converts dates to and from string format (MM/DD/YYYY or DD.MM.YYYY) to numeric format NNNNNNNN FORMAT: @Jx or @Yx where 'x' references a @Zx variable. @Jx - Converts a date (MM/DD/YYYY or DD.MM.YYYY) stored in variable @Zx to a numeric string representing the number of days from 01/01/1900 (01.01.1900). For Example, if the date in @Z5 contains "06/01/1989", then issuing @J5 would overwrite the equivalent number of days between 01/01/1900 and 06/01/1989 in @Z5. Variable @Z5 can then be assigned to a numeric variable (@Nx) for further manipulation. The date string in @Zx prior to calling the @Jx function can be stored in either US or European format and can be in the short form (ie: 1/6 or 6.1 or 1/6/2). Note that if the date string is in error, the function will overwrite the @Zx variable with the numeric string "0" (without the quotes). The following example of using the @Jx variable demonstrates how it could be put to use on a subscription BBS which relies on the MEMODATE2 field: @z1=o17; @c3 Get Today's date @c4 @z2=u23; @c3 Get User's MEMODATE2 @c4 @j1 @j2 @n1=z1; @n2=z2; @n0=(n2-n1); Your subscription expires in @n0; days! @Yx - The opposite of @Jx. Converts a numeric string stored in variable @Zx, overwriting the @Zx variable with the date in MM/DD/YYYY or DD.MM.YYYY format depending on the users dateformat setting. Note that if the value in the @Zx variable is in error (ie: a negative number), the @Zx string will be overwritten with 01/01/1900 (or 01.01.1900 depending on the user's dateformat setting). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-19 Call Command (@K) @K Command PURPOSE: Calls a routine located at label @Px. Returns to area following the call upon a return (@#) instruction. FORMAT: @K(exp); @K(exp); - Same as @B(exp); but Kalls (calls) the part of the file identified by a @Px label. The result is identical to the @B(exp) command, but the return address is saved on an internal stack. To return back to the position after the @K(exp); is issued, issue the new MILC command @# to signify a return command. Example: @B1; unconditional branch to @P1 . . @P5 Label (signifies branch address) . . . @# Branch back to caller if called . by a @K(exp) command. . @P1 . . @K5; Branch (Kall) code at @P5 . Return to next instruction (here) . when done Kalls (calls) can be nested up to 50 levels. The MILC command @# ends the call, and returns processing back to the place in the file immediately preceeding the @K(exp); command. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-20 Customizing MAGNUM - Display Files/MILC Commands Security Level Commands (@L) @L Command PURPOSE: Processes all following text and commands for a specific security level only. FORMAT: @Lx where 'x' is a security level The @Lx command allows text/commands to be displayed/processed only if the remote user viewing the file has a security level equal to 'x'. The command @L10 for example, activates this feature such that the file display functions will only display text and process commands if the current user has a security level of 10. For Users at higher or lower levels, the command will act identically to the @C3 command. This will continue until another @Lx command is issued, which changes the security level again. To revert back to normal processing, the command @L0 will negate the @Lx command. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-21 Match Filename in FILE DATAbase (@M) command @M Command PURPOSE: Matches a Filename in the FILE DATAbase in preparation for external protocol(s). FORMAT: @Mx where 'x' references a @Zx variable. @Mx - Match filename in the FILE database. In preparation for external protocols, if a filename is in variable @Zx, the @Mx command will return the complete filespec (drive,path,filename,ext) in @Zx. For example, if the filename MAGNUM2.ZIP is in variable @Z5, then @M5 would overwrite @Z5 with D:\MAGNUM\GILMORE\MAGNUM2.ZIP or whatever the matching filespec would be for the file. If the filename is not found, or the filename is in a file area inaccessible to the user, then @Z5 will be null upon return from the @M5 function. If the filename is password protected, the user will be prompted for the password - if the password is wrong, the @Z5 variable will become null. If the value of x for @Mx is >= 40, then the following format is returned in variable @Zx: d:\path\filename[.ext] nnnnnn mm/dd/yyyy | | |_______ file date | |________________ file size |________________________________ filespec otherwise, if the value of x for @Mx is < 40, then the following format is returned in variable @Zx: d:\path\filename[.ext] MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-22 Customizing MAGNUM - Display Files/MILC Commands Numeric (@N) Commands (ie: mathematics, I/O, etc) @N Command PURPOSE: Numeric variable command. Performs arithmetic functions, screen I/O, and file writes. FORMATs: @Nx; Prints contents of @Nx @Nx=Ny; Assigns contents of @Ny to @Nx @Nx=y; Assigns a value to @Nx (ie: @N1=12;) @Nx(a,b); Assigns remote user's input to @Nx @Nx=Zy; Converts string variable @Zy to numeric, assign to @Nx @Nx=(EXP); Performs a mathematical expression @Nx("string"); Writes "string" to disk, followed by contents of @Nx where 'x' is the variable identifier (0 to 99), 'a' and 'b' are numbers, EXP is an arithmetic expression, "string" is a character string, 'y' is a number. The @Nx command is a very powerful command in that it performs many different tasks. It is capable of user input, screen or file output, performing arithmetic expressions, conversion of @Zx (string) variables to numeric, etc. There are 100 different numeric variables available (identified as @N0 to @N99). Each one of these is unique, and is capable of doing 32-bit arithmetic (long integers). This means that values can range from minus 2 billion something to plus 2 billion something. That's a fairly wide range. Note that floating point is NOT supported since it would take up too much program space and require too much processing time. You can, however make it appear as though floating point is supported by using a technique called scaling. It is beyond the scope of this document to cover scaling techniques, but if you are familiar with scaling you should have no problems. Note that all @N commands must end with the ';' (semicolon) character! Let's go through the different capabilities: DISPLAY THE CONTENTS OF A NUMERIC VARIABLE: This is the simplest form of the @N commands. Simply "@Nx;" (without quotes) where 'x' is the numeric variable (0 to 99) that you wish the contents displayed. If @N5 had the value 2005 in it, then the command @N5; embedded anywhere within the file will display "2005" (without quotes) on the remote user's screen. ASSIGNMENT TO A NUMERIC VARIABLE: This is the next simplest form of the @N command. Let's suppose that MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-23 Numeric (@N) Commands (ie: mathematics, I/O, etc) the numeric variable @N4 had the value 250: @N1=N4; @N2=12; In the above two examples, the contents of @N4 (which we said was 250) is assigned to @N1, therefore @N1 and @N4 now both hold the value 250. In the @N2 assignment, the value 12 is being assigned to @N2. GETTING REMOTE USER's NUMERIC INPUT: The @N command can also ask the remote user to input a number. The format of this form of the @N command is: @Nx(a,b); where 'x' (as usual) represents which N variable you want (0 to 99), and 'a' and 'b' represent the allowable range of numbers the user can enter. For example: Please Enter Your Age => @N1(5,120); This would print "Please Enter Your Age => " and wait for the user to enter a numeric response. Once the user enters their response, it is checked to see if it falls within the range of 5 to 120 (inclusive) and if it does, it assigns their answer to variable @N1. If it does not fall within the accepted range, a beep is emitted on the remote user's terminal and they are required to re-enter their answer. The display of the file will not continue until the remote user has entered an acceptable number. CONVERTING A STRING VARIABLE (@Zx) TO NUMERIC: The @Nx command is capable of converting a string variable to numeric, provided that the string variable consists of digits. If it does not consist of digits, the value 0 will be assigned to the numeric variable. Note that a numeric string of "0" and "John" will both result in the @Nx variable being assigned the value of 0. Some examples follow: @Z5="365"; @N2=Z5; @N2; In the above example, the string variable @Z5 is assigned the string "365". The next statement - @N2=Z5; - converts the string "365" to numeric and assigns the result in @N2. The next statement displays the value of @N2 which is 365. PERFORMING MATHEMATICS: And now for the real power of the @Nx command - mathematics! An example follows: @N5=365; @N4=(N5/7); There are @N4; weeks in a year. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-24 Customizing MAGNUM - Display Files/MILC Commands Numeric (@N) Commands (ie: mathematics, I/O, etc) In the above example, @N5 is assigned the value 365. Next, @N4 is assigned the result of the expression (N5/7) which is identical to 365/7, yielding a result of 52. Then "There are 52 weeks in a year." is displayed. As mentioned earlier, floating point is not supported. Therefore, the result of 365/7 is 52 (not 52.14286) - the decimal portion is simply truncated (dropped) - not rounded. The format @Nx=(EXP); for the (EXP) part must follow 3 rules: The expression must be enclosed in parenthesis. The first parameter MUST be a @N variable. The second parameter can be either a @N variable or number. In other words, @N5=(N10+12); is correct. @N5=(N10+N30); is correct. @N5=(45+N3); is incorrect. @N5=(45+70); is incorrect. As always, note the lack of any spaces, and the terminating ';'. The operation to be performed in the EXP part of the example can be one of: + addition - subtraction * multiplication / division % modulus (remainder) ^ XOR (bitwise exlusive or) | OR (bitwise OR) & AND (bitwise AND) Most of you will be using the first 4 operations. The next 4 (%,^,|,&) are beyond the scope of this document, therefore - if you are not familiar with what a modulus, XOR, OR, or AND are then you will have no need for them anyway. WRITING THE @Nx VARIABLE TO DISK: With all the power of the @Nx command, it would certainly be a shame if there were no way to write the contents of some of the variables to disk. This is handy with such files as Questionairres. To write the contents of a @Nx variable to disk, simply: @N5("Total Price: $"); Assuming @N5 had the value 500. The above statement would write the following line to a disk file: Total Price: $500 Another example might be: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-25 Numeric (@N) Commands (ie: mathematics, I/O, etc) @Z1=O10; @N1=Z1; @N2=72; @N1(N2-N1); @N1("Years left for average life expectancy: "); Assuming the user's age is 25, we place the user's age (see @O command) in the variable @Z1. Next, we assign the numeric equivalent to numeric variable @N1. Numeric variable @N2 is assigned the value 72. We then assign to @N1 the result of the expression (N2-N1) or 72-25. The following line then gets printed to disk: Years left for average life expectancy: 47 Which file does it write to? Whatever file is currently being displayed, the output file will have the same name but with an extension of ".R??", where the "??" will be replaced with the com port number the user is logged on to. The output file will always be placed in the SYSOUT directory. So if the user was displaying "c:\gs\com\1\bul_dir\ques1" or "c:\gs\com\1\bul_dir\ques1.bbs" or "c:\gs\com\1\bul_dir\ques1.scr" the output file will be "ques1.r01" if the user is on com port 1, "ques1.r02" if the user is on com port 2, etc the output file will always be placed in the SYSOUT DIRECTORY. The 'R' in ".R01", ".R02", etc stands for "Response" since we are normally writing the user's responses to the output file. We used the above example file names since they are all the same - the extension simply gets stripped off, and replaced with the ".R??" extension (as explained above), while the path is changed to point to the session directory. It's that simple! Note that if the response file does not exist, it will be created. If the response file already exists, it will be appended to. How do we know which user was online at the time we wrote the answers to the disk file? When the very first response gets written to the response file, the system will write the user's name, id number, date, time and some other info to the file before writing the response to the file. AN EXAMPLE QUESTIONAIRRE FILE: Questionairre #2 - Fictitious credit card order @P1 1) Credit Card # => @Z0(20); @P2 2) Purchase of: A) 20 Mb Hard Disk ($100) B) 2400 baud modem ($ 95) C) Personal Computer ($900) D) MBBS for OS/2 ($400) Choice (A, B, C or D) => @Z1('ABCD'); @b40(Z1="A"); @b41(Z1="B"); @b42(Z1="C"); @b43(Z1="D"); MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-26 Customizing MAGNUM - Display Files/MILC Commands Numeric (@N) Commands (ie: mathematics, I/O, etc) @P3 Your order for $@n1;.00 + $10.00 for shipping/handling comes to a grand total of @n2=(n1+10);$@n2;.00 Is all of the above information correct (Y/N) => @Z2('yn'); @B1(Z2="N"); @Z0("Credit Card # "); @Z3("Purchased: "); @N2("Total Price: $"); @b49(0=0); @p40 @n1=100; @Z3="20 Mb Hard Disk"; @b3(0=0); @p41 @n1=95; @Z3="2400 baud modem"; @b3(0=0); @p42 @n1=900; @Z3="Personal Computer"; @b3(0=0); @p43 @n1=400; @Z3="MBBS for OS/2"; @b3(0=0); @p49 Thank you for your order, @u3 We'll be sending that off to: @u3 @u4 @u2 @u6 @u7 @u8, @u9, @u10 @u11 @c9 Assuming "ques2.bbs" is the questionnaire, and the user on node 1 completed it, the response file "ques2.r01" will be logged in the SYSOUT directory. A typical might look like the following: ------------------------------------------------------------ **** USER: JOE S USER ****** ID: "/3" AGE: 36 **** FROM: self 123 Sesame St. Los Angeles, CA 90067 - USA ** PHONE1: 213-555-2125 PHONE2: 213-555-1900 ext 25 * * * ANSWERS LOGGED AT 18:43 on Thursday, 13 April 1989 Credit Card # 1234-123-123-123 Purchased: MBBS for OS/2 Total Price: $410 ------------------------------------------------------------ **** USER: JOHN K DOE ****** ID: "/248" AGE: 22 **** FROM: Unlimited Products, Inc. 24 Tower Drive, Suite 135 Chicago, IL 60601 - USA ** PHONE1: (312) 555-4321 PHONE2: (312) 555-1234 * * * ANSWERS LOGGED AT 20:02 on Thursday, 13 April 1989 Credit Card # 1234-5678-9012-3456 Purchased: 2400 baud modem Total Price: $105 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-27 Other (Miscellaneous) Commands (@O) @O Command PURPOSE: 'OTHER' (miscellaneous) information will display about the system date and time, and other miscellaneous information. FORMAT: @Ox where 'x' is the parameter (a number) representing what to display. The command @Ox in a display file will be replaced with information about the system date, time or other miscellaneous information depending on the value of the 'x' parameter. The 'x' parameter can range from 0 to 21 as follows: @O0 - Hours (ranges from 00 to 23) @O1 - Minutes (ranges from 00 to 59) @O2 - Seconds (ranges from 00 to 59) @O3 - Hundredths of seconds (ranges from 00 to 99) @O4 - Day of month (ranges from 00 to 31) @O5 - Month (ranges from 01 to 12) @O6 - Year (the current 4-digit year) @O7 - Day of week (string: "Sunday", "Monday", etc) @O8 - Month (string: "January", "February", etc) @O9 - Time (string: "3:57 PM", "12:01 AM", etc) @O10 - User's age @O11 - Minutes user has been online this call @O12 - NODE # user is on @O13 - Total calls received on PORT # @O14 - Previous caller's name (up to 62 chars) @O15 - Previous caller's location (up to 62 chars) @O16 - Magnum Version Number (up to 9 chars) @O17 - Current date in either MM/DD/YYYY or DD.MM.YYYY format depending on the user's dateformat setting. @O18 - Used for creating a random 8-digit string. This is MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-28 Customizing MAGNUM - Display Files/MILC Commands Other (Miscellaneous) Commands (@O) related to RJE programs, such that if someone starts the same RJE program more than once, you don't want it writing its output to the same filename every time. This command provides a unique way of creating a filename which is unique (less the extension) to pass to RJE or other programs external to Magnum requiring an output filename to write to. Example: @z0="pgmname.exe"; @z1=o18; @z1=(z1+".txt"); @e1 The string returned is time-dependent. It consists of: HHMMSShh where: HH = current hour of current day MM = current minute of current day SS = current seconds of current day hh = current hundredths of seconds of current day @z1=o18; is identical to doing the following: @z1=z0; @z2=o1; @z1=(z1+z2); @z2=o2; @z1=(z1+z2); @z2=o3; @z1=(z1+z2); @O19 - Logon type: L = Local Logon (keyboard/console or local logon module) R = Remote Logon (modem) PF = Pipe in Full Duplex (OS/2 workstation) PH = Pipe in Half Duplex (DOS workstation) Half duplex pipes have the following restrictions: - Cannot stop displays with <Ctrl-X> or <SpaceBar> - Cannot run interactive child (door) programs unless those programs conform to Magnum's duplex-switching scheme (contact Gilmore Systems for more information). - Chat mode not allowed. @O20 - The 10-digit Serial Number of Magnum for THIS machine. @O21 - The 10-digit Parent Serial Number of Magnum. @O22 - "TRUE" or "FALSE" (without the quotes) if the system has the 'Extended FileBase' option. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-29 Other (Miscellaneous) Commands (@O) @O23 - "TRUE" or "FALSE" (without the quotes) if the system has the 'Extended MsgBase' option. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-30 Customizing MAGNUM - Display Files/MILC Commands Position (Label) Commands (@P) @P Command PURPOSE: Defines a POSITION (LABEL) in a file to be a target for a BRANCH command. FORMAT: @Px where 'x' is the label number. The POSITION (or LABEL) command simply marks a place in the display file for later use as a target for a BRANCH instruction. 'x' can range from 0 to 99. See the @B command for examples. NOTE: 'x' must fall within the range of 0 to 99. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-31 Retain (@R), File (@F) and Query (@Q) MILC Variables @Z & @N @R Command PURPOSE: To retain the values of all @Zx and @Nx MILC variables such that they can be used by other files. (IE: MAKES @Zx and @Nx variables GLOBAL). @FORMAT: @Rx where 'x' is one of 0 or 1 as follows: @R1 - retain contents of @Zx and @Nx variables after file display. @R0 - do not retain contents of @Zx and @Nx variables (default). Whenever the display routines come across the @R1 command within a display file, the @Nx and @Zx variables will be retained. This means that any subsequent display file can use the previously stored values stored within these variables. Note that the use of @R1 makes these variables global, so if one display routine changes the contents of any given variable, all subsequent display routines will find the value to be that of the most recent assignment statement to the variable(s). Note that the @Ix command ("include") will remain unaffected by the @R1 command. To negate the @R1 command, simply issue a @R0 command and the file display routines will return to the normal way in which Magnum used to process its MILC commands. When the display file routine starts, it initializes all @Zx variables and to nul (""), and all @Nx variables to zeros (0). The @R1 command merely tells the file display routine not to do this for all subsequent file displays. The @R0 command negates this, causing the file display routines to reinitialize all @Zx and @Nx variables. CAUTION: User messages (in the message section) will result in the @Nx and @Zx variables not being initialized (ie: they will have access to the values stored in these variables). Note that users having access to MILC commands within messages will overwrite these values!! It would be a wise precaution to issue a @R0 command prior to entering the message menu. NOTE that any text display you've created the old way which depends on @Nx and @Zx variables being initialized to zeros and nulls should be modified such that they perform their own initialization (this could easily be accomplished by including an initialization file with the @I4 command. Because of the problems which might occur with the globality aspect of using the @R1 command above, another solution (and much greater power as a result) is to have the contents of the @Zx and @Nx variables saved in a unique file. This can be accomplished with two new MILC variables: @Fx - where 'x' is a unique file identifier which can range from 0 to 99. When an @Fx command is invoked, the contents of the @Zx and @Nx variables are saved to a unique filename which you will know as 'x'. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-32 Customizing MAGNUM - Display Files/MILC Commands Retain (@R), File (@F) and Query (@Q) MILC Variables @Z & @N @Qx - where 'x' is a unique file identifier which can range from 0 to 99. When an @Qx command is invoked, the contents of the @Zx and @Nx variables are restored from the unique filename which the @Fx command saved them to. When using @Fx to save your variables and @Qx to restore them, you don't have to use the @R1 command. However, the @Fx and @Qx functions have advantages and disadvantages over using the @R1 function. For example, with @Fx and @Qx, any subsequent display file must know which 'x' file to restore from. On the other hand, the @R1 function makes the variables global across the board which would proably not be a good idea when doing messages. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-33 Stack Keystrokes Command (@S) @S Command PURPOSE: Places Keystrokes in the user's command stack, as if the user typed in the characters him/herself. FORMAT: @Sx where 'x' refers to which @Zx variable to stack from. This command places characters in the user's command stack. The 'x' tells which @Zx variable to place the commands in the stack from. For example, if reading a display file from the main menu, you could place the user in the [F]iles menu looking at all new files since their last logon with the following: @Z7="\\f\n\+\\"; @S7 @C16 Note that because the semicolon (;) character is the terminataion character of a string assignment, that character cannot be used within the string itself! The @Sx command, while copying the contents of the @Zx variable containing the string to place in the command stack, converts all backslash (\) characters to semicolons. In the above example, the @S7 command would place the following in the user's command stack: ;;f;n;+;; Note that this only PLACES commands in the user's command stack. Upon ending (or terminating with @C16) the display, all system input (prompts) will get their input from the keystrokes now stored in the user's command stack until the last keystroke stored is read. Magnum will revert back to getting its input from the user (modem) when no more keystrokes remain in the command stack. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-34 Customizing MAGNUM - Display Files/MILC Commands Text to Log (activity) File (@T) @T Command PURPOSE: Sends text within a quoted string or a @Zx variable to the ACTIVITY.x file. FORMAT: @Tx @T"string" This command writes to the ACTIVITY.x file. There are two ways to send text to the ACTIVITY.x file: The following example writes the text appearing within the double-quotes to the ACTIVITY file: @T"This is a sample text line" The following example writes the contents of variable @Z5 to the ACTIVITY file: @T5 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-35 User Substitution Commands (@U) @U Command PURPOSE: 'USER' information will display. Ideally suited for giving the illusion of a customized display file to the user. FORMAT: @Ux where 'x' is the parameter (a number) representing what to display. The command @Ux in a display file will be replaced with information about the user depending on the value of the 'x' paramter. The 'x' parameter can range from 0 to 75 as follows: @U0 - Deleted or active user. Displays "deleted" or "active". @U1 - Displays User's ID number. Up to 10 chars. @U2 - Displays user's LAST name. Up to 20 chars. @U3 - Displays user's FIRST name. Up to 20 chars. @U4 - Displays user's MIDDLE name. Up to 10 chars. @U5 - Display's "Private Messages" or "No Private Messages" @U6 - Displays user's STREET1 (or company name) - up to 40 chars. @U7 - Displays user's STREET2 (or street address) - up to 40 chars. @U8 - Displays user's CITY - up to 20 chars. @U9 - Displays user's STATE or PROVINCE - up to 20 chars. @U10 - Displays user's ZIP or other postal info - up to 20 chars. @U11 - Displays user's COUNTRY - up to 20 chars. @U12 - Displays user's PASSWORD - up to 20 chars (be carefull!) @U13 - Displays date of user's FIRST CALL (10 chars) @U14 - Displays date of user's LAST CALL (10 chars) @U15 - Displays time of user's LAST CALL (5 chars) @U16 - Displays user's DATE OF BIRTH (10 chars) @U17 - Displays user's PHONE #1 (up to 20 chars) @U18 - Displays user's PHONE #2 (up to 20 chars) @U19 - Displays user's LAST "NEW FILES" search date (10 chars) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-36 Customizing MAGNUM - Display Files/MILC Commands User Substitution Commands (@U) @U20 - Displays user's CPU TYPE (15 chars) @U21 - Displays user's CONFERENCE letters (up to 26 chars) @U22 - Displays user's MEMODATE #1 (10 chars) @U23 - Displays user's MEMODATE #2 (10 chars) @U24 - Displays sysop's COMMENT about user (up to 60 chars) be careful with this one! @U25 - Displays user's selected FILE XFER PROTOCOL (up to 10 chars) @U26 - Displays user's PERIOD TYPE (up to 5 chars) @U27 - Displays "Expert" or "Novice" menu types. @U28 - Displays "Authorized" or "Unauthorized" (is user locked out?) @U29 - Displays user's color settings ("color" or "B/W") @U30 - Displays user's setting of "'More' prompt" or "No 'More' prompt" @U31 - Displays "Erase 'More' prompt" or "Do not erase 'More' prompt" @U32 - Displays "Single-keystroke commands" or "C/R" @U33 - Displays "Message Deletion" or "No Message Deletion" @U34 - Displays user's LINES PER SCREEN (up to 3 chars) @U35 - Displays user's SECURITY LEVEL (up to 5 chars) @U36 - Displays user's # OF FILES UPLOADED (up to 5 chars) @U37 - Displays user's # OF FILES DOWNLOADED (up to 5 chars) @U38 - Displays user's ADJUSTED CHARS/SEC XFER RATE (up to 5 chars) @U39 - Displays user's UL/DL RATIO (up to 10 chars - ie: "10 to 1") @U40 - Displays user's TOTAL CALLS (up to 10 chars) @U41 - Displays user's MINUTES REMAINING FOR THIS CALL (up to 10 chars) @U42 - Displays user's MINUTES REMAINING FOR THE PERIOD (up to 10 chars) @U43 - Displays user's LAST MSG NUMBER READ (up to 10 chars) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-37 User Substitution Commands (@U) @U44 - Displays user's ACCUMLATED UPLOAD K BYTES (up to 10 chars) @U45 - Displays user's ACCUMLATED DOWNLOAD K BYTES (up to 10 chars) @U46 - Displays user's ALLOWED NUMBER OF D/L's FOR PERIOD (up to 10 chars) @U47 - Displays user's ALLOWED DOWNLOAD K BYTES FOR PERIOD (up to 10 chars) @U48 - Displays user's BAUDRATE (up to 5 chars) @U49 - Displays "Modem Error Correction" or "No Modem Error Correction" @U50 - Displays allowable "@" commands for messages (up to 26 chars) @U51 - Displays User Date Format ("U.S." or "EUROPE") @U52 - Displays a string of up to 26 chars showing the user's FREE download areas) @U53 - Displays the number of FREE downloads a user has performed @U54 - In preparation for running certain externals created by Gilmore Systems, this MILC command supplies the complete filespec (drive,path,filename) for the MBBSINIT.x file associated with the node the user is on. @U55 - Like @U54 above, but supplies filespec for STARTUP.x instead. This is in preparation for running externals created from 3rd party software developers. @U56 - User's MSG_R_AREAS (up to 26 chars) @U57 - User's MSG_W_AREAS (up to 26 chars) @U58 - User's MSG_L_AREAS (up to 26 chars) @U59 - User's FILE_U_AREAS (up to 26 chars) @U60 - User's FILE_D_AREAS (up to 26 chars) @U61 - User's FILE_L_AREAS (up to 26 chars) @U62 - Displays a string of up to 78 characters showing the user's areas of personal interests. @U63 - User's compression default type "ARC" or "ZIP" (w/o quotes). @U64 - Number of PUBLIC messages entered by user. @U65 - Number of PRIVATE messages entered by user. @U66 - Number of RJE Jobs run by user. @U67 - The complete filespec (drive,path,filename) of the last MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-38 Customizing MAGNUM - Display Files/MILC Commands User Substitution Commands (@U) message saved by the user. Note that the REF# of last message saved for any external programs you may have written can be derived from the filespec of the message. For example: Filespec: D:\MAGNUM\MSG_DIR\K\K1234567.890 Ref#: K1234567890 Note that a CC (Carbon Copy) is not considered to be a message saved. In the case of saving a message with CC's, only the original message will be deemed to be the 'last message saved'. @U68 - the complete filespec (drive, path, filename) of the last file the user uploaded during THIS session. This variable is ideally used to pass this information to an external program right after the user performs a file upload. This can be accomplished with the POSTUP.BBS display file. @U69 - the current MessageBase the user is in. @U70 - the current FileBase the user is in. @U71 - Returns Y or N depending on whether the user's ID is reusable. @U72 - Returns user account type (U or M). U=user, M=mail. @U73 - Returns Y or N depending on if the user can use Remote Mail. @U74 - Returns the MSG GROUP assigned to this user (0-255). @U75 - Returns the FILE GROUP assigned to this user (0-255). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-39 View System Variables (@V) @V Command PURPOSE: Allows static information about the system/session to be viewed and/or passed to external programs. FROMAT: @Vx (where 'x' is the one of the system variables described below. These variables are generally viewed or assigned to a @Zx variable). System related information can be used to pass as information to external programs. These variables are not changeable (most are changeable by "re-compiling" your STARTUP files), which is why we call it the VIEW command rather than something else). The @Vx command can be used much like the @Ux and @Ox command in that it can be assigned to a @Zx variable. The @Vx commands are as follows (where 'x' is the static variable you wish to use): 0 = Comport handle (ie: to pass to an external program such as an external file xfer program). NOTE: The comport handle is NOT automatically passed to child processes. To pass the handle, you will need to do two things: - Make the child process aware of the handle number by including the contents of @V0 on the command line: @z1=v0; - The comport handle is automatically marked UN-INHERITABLE to child processes. The 128 bit of MILC variable @N0 is used to tell Magnum that the comport handle is to be inherited by your external child process. Simply OR the value 128 into the @N0 variable: @n0=7; @n0=(n0|128); See the description of CHILDREN.BBS in the "Creating Subdirectories" portion of the manual. 1-26 = The actual DIRECTORIES of file areas A thru Z, such that 1=file directory A, 2=file directory B,...26=file directory Z. 27-52 = The actual file DESCRIPTION strings for file areas A thru Z such that 27=file description A, ... 52=file description Z. 53-78 = The actual message DESCRTIPTION strings for message conference areas A thru Z such that 53=message description A, ... 78=message description Z. 79 = The PROGRAM directory. 80 = The SESSION directory. 81 = The BULLETIN directory. 82 = The MENU directory. 83 = The HELP directory. 84 = The DISPLAY directory. 85 = The EXTERNAL directory. 86 = The RJE directory (where RJE programs and menu(s) are). 87 = The MESSAGE directory (parent directory only, there are 26 subdirectories (A-Z) under this). 88 = The WORK directory. 89 = The USERS directory. 90 = The SYSOUT directory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-40 Customizing MAGNUM - Display Files/MILC Commands View System Variables (@V) 91 = The RJE RESULTS directory (it's one of your FILE directories). 92 = ACTIVITY.x handle (ie: to pass to an external program such as an external file xfer program). NOTE: The ACTIVITY.x handle is NOT automatically passed to child processes. To pass the handle, you will need to do two things: - Make the child process aware of the handle number by including the contents of @V92 on the command line: @z1=v92; - The ACTIVITY.x handle is automatically marked UN-INHERITABLE to child processes. The 64 bit of MILC variable @N0 is used to tell Magnum that the ACTIVITY.x handle is to be inherited by your external child process. Simply OR the value 64 into the @N0 variable: @n0=7; @n0=(n0|64); See the description of CHILDREN.BBS in the "Creating Subdirectories" portion of the manual. - NOTE: The child process inheriting this handle may use it for WRITE-ONLY (the handle is not available for reading). 93 = The PID (process identification number) of MSESSION.EXE for this session. The PID will be non-zero if this call is successful. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-41 Wait Command (@W) @W Command PURPOSE: Waits a specified number of miliseconds, then continues. FORMAT: @Wx where 'x' is the number of miliseconds to wait. The WAIT (or pause) command, waits 'x' number of miliseconds, then continues. This command is useful in your GOODBYE.BBS file to create a pause while the modem empties its buffer to the user prior to disconnecting. For example, @W2000 will cause a delay of 2 seconds before proceeding - this is usually sufficient to empty the modem's buffer before ending the GOODBYE.BBS file. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-42 Customizing MAGNUM - Display Files/MILC Commands String (@Z) Commands (ie: String Logic, I/O, etc) @Z Command PURPOSE: String variable command. Performs string functions, screen I/O, and file writes. FORMATs: @Zx; Prints contents of @Zx @Zx=Zy; Assigns contents of @Zy to @Zx @Zx="string"; Assigns a string to @Zx (ie: @Z1="John";) @Zx('abc'); Get's remote user's input - restricts input to 'abc' @Zx(y); Get's remote user's input - up to 'y' chars. @Zx=Ny; Converts numeric variable @Ny to string, assign to @Zx @Zx=Oy; Assigns contents of @Oy to @Zx (See @O) @Zx=Uy; Assigns contents of @Uy to @Zx (See @U) @Zx=Vy; Assigns contents of @Vy to @Zx (See @V) @Zx(EXP); Performs a string expression (concatenation) @Zx("string"); Writes "string" to disk, followed by contents of @Zx where 'x' is the variable identifier (0 to 99), 'abc' are characters, EXP is a string expression, "string" is a character string, 'y' is a number. The @Zx command is a very powerful command in that it performs many different tasks. It is capable of user input, screen or file output, performing string concatenations, conversion of @Nx (numeric) variables to string, etc. There are 100 different string variables available (identified as @Z0 to @Z99). Each one of these is unique, and is capable of storing strings of up to 112 characters each. Note that all @Z commands must end with the ';' (semicolon) character! Let's go through the different capabilities: DISPLAY THE CONTENTS OF A STRING VARIABLE: This is the simplest form of the @Z commands. Simply "@Zx;" (without quotes) where 'x' is the string variable (0 to 99) that you wish the contents displayed. If @Z5 had the string "John" in it, then the command @Z5; embedded anywhere within the file will display "John" (without quotes) on the remote user's screen. ASSIGNMENT TO A STRING VARIABLE: This is the next simplest form of the @Z command. Let's suppose that the numeric variable @Z4 had the value "Good Morning": MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-43 String (@Z) Commands (ie: String Logic, I/O, etc) @Z1=Z4; @Z2="John"; In the above two examples, the contents of @Z4 (which we said was "Good Morning") is assigned to @Z1, therefore @Z1 and @Z4 now both contain the string "Good Morning". In the @Z2 assignment, the string "John" is being assigned to @Z2. GETTING REMOTE USER's STRING INPUT: The @Z command can ask the remote user to input a string or a single character. By way of example, let's demonstrate the two forms of string or single-character input: @Z5(20); Accepts up to a 20-character string, assigns to @Z5 @Z6('YN'); Accepts either the 'Y' or the 'N' character - nothing else. Assigns the string "Y" or "N" to @Z6. As a working example, let's ask the user for their favorite sport: What is your favorite sport => @Z1(20); This would print "What is your favorite sport => " and wait for the user to enter a response of up to 20 characters. When the user presses his ENTER (or C/R) key, whatever they typed will be assigned to string variable @Z1. Note that responses are always required! Many times, you'll be offering the user a choice (Y/N) or a menu selection that requires a single-character response. For example: Are you sure (Y/N) => @Z1('yn'); would print "Are you sure (Y/N) => " on the user's screen, then wait for the user to respond with 'y' or 'n' before continuing. Note that upper/lowercase is not important - 'y' is the same as 'Y' as far as the system is concerned. Also note that if the user's environment settings is set for single-character responses, the system will not wait for them to press ENTER (or C/R) before continuing, otherwise their single-character response will not be processed until they press ENTER (or C/R). In the above example, the user's response will be stored as a single-character string in variable @Z1. Note that we will use double quotes (" ") to denote strings, and single quotes (' ') to denote single characters. In a menu or multiple choice type of situation, the following might be found: A) True B) False C) Could go either way D) I don't know MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-44 Customizing MAGNUM - Display Files/MILC Commands String (@Z) Commands (ie: String Logic, I/O, etc) Enter your choice => @Z2('abcd'); You are not limited by alphabetic characters either, the above could be represented with single-digit numbers as well: 1) True 2) False 3) Could go either way 4) I don't know Enter your choice => @Z2('1234'); Or it could contain a mixture: A) Some of the time 1) Skip this question B) Most of the time 2) Quit, return to system C) None of the time D) All of the time Enter your choice => @Z2('abcd12'); CONVERTING A NUMERIC VARIABLE (@Nx) TO STRING: The @Zx command is capable of converting a numeric variable to string. Suppose that @N2 had the numeric value of 365: @Z5=N2; In the above example, the numeric variable @N2 has a value of 365. This is converted to the string "365" and assigned to string variable @Z5. GETTING MISCELLANEOUS SYSTEM OR USER INFORMATION: The @Zx command can also be assigned any of the @Ox, @Ux or @Vx strings. See @O, @U, @V commands for their parameters. For example: @Z1=O10; assigns the user's age (as a string) to string variable @Z1 Remember that the @Nx (numeric) variables cannot obtain any @O or @U values. @Nx values can only obtain those values from @Zx variables: @Z1=O10; @N1=Z1; This assigns the user's age to string variable @Z1, then converts the numeric string in @Z1 to numeric for assignment to @N1. PERFORMING STRING CONCATENATION: String concatenation is simply taking two strings, and combining them MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-45 String (@Z) Commands (ie: String Logic, I/O, etc) into one - as long as the resultant string is 112 characters or less. Examples: Suppose that @Z1 contained the string "Bed": @Z1=(Z1+" time"); would result in @Z1 containing "Bed time". or @Z1=(Z1+"time"); would reslut in @Z1 containing "Bedtime". Suppose that @Z1 contains "John", and @Z2 contains "is 25 years old": @Z3=(Z1+Z2); would result in "Johnis 25 years old" You might need 2 steps in that case: @Z3=(Z1+" "); @Z3=(Z3+Z2); would result in "John is 25 years old" WRITING THE @Zx VARIABLE TO DISK: With all the power of the @Zx command, it would certainly be a shame if there were no way to write the contents of some of the variables to disk. This is handy with such files as Questionairres. To write the contents of a @Zx variable to disk, simply: @Z5("Favorite Sport: "); Assuming @Z5 contained the string variable "swimming", the above command would write the following line to a disk file: Favorite Sport: swimming Basically, writing either a @Zx or @Nx variable to disk is the same. The format for @Zx variables are: @Zx("string"); The format for @Nx variables are: @Nx("string"); where 'x' is the number of the string or numeric variable you want written, and "string" is any descriptive string you want (as an aid in telling you what you've written). See the @N command "Writing the @Nx VARIABLE TO DISK" section for more examples and an explanation of what files actually get written to. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-46 Customizing MAGNUM - Display Files/MILC Commands Character Display - @\ command. @\ Command PURPOSE: Force display of a character. FORMAT: @\x Displays character equivalent of 'x'. The IBM character set contains 256 characters (values 0 to 255). Note that if you're using a 7 databit setup only characters 0 to 127 are available, however, 99% of all BBSs are running an 8 databit setup. Unfortunately, many of you are limited as to what characters can appear in your display files by the characters which are on your keyboard. For example, there's no BEL character on your keyboard (sends an audible beep to the remote user). This is where the @\x command comes in. The command: @\7 sends a BEL character to the screen (and comport). Other examples: @\13 CR (carriage return) @\10 LF (line feed) Valid values are @\0 through @\255 exluding the @\17 (XON) and @\19 (XOFF) equivalents. If @\x has a negative value, or a value of 17, 19, or greater than 255, then the statement is ignored. Note that the number used as 'x' in a @\x statement is terminated by the first non-digit. Therefore, if you wanted to a display a numeric character following a BEL (@\7) such as the number 10, then the statement @\710 will NOT work. One alternative around this might be the following: @N2=10; @\7@n2; or @N2=10; @\7@\[2] (See "Indirect Addressing" later in this chapter) Using the advanced features of Indirect Addressing (explained on the pages of this chapter entitled "Advanced MILC Command Usage - Indirect Addressing"), the following example demonstrates how to display the entire character set: @N5=0; @P0 @\[5+] @B0(N5<256); NOTE: The @\x command is available to ALL users, and is NOT part of the DISP_CMDS field of each user's record. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-47 "Sysop Only" MILC commands: @$x, @&x, @!x, and @?x Four MILC commands are designated "sysop use only". These are not part of the DISP_CMDS field of any user record including the sysop. The commands perform the following functions: @$x - Save @Zx and @Nx values to a file in MBBSEXEC format @&x - Restore @Zx and @Nx values from a file in MBBSEXEC format. @!x - Delete a file. @?x - Check for file existence. @$x - Save @Zx and @Nx values to a file in MBBSEXEC format This command will save the values of all of the @Zx and @Nx variables in a file compatible with MBBSEXEC format (see MBBSEXEC - Advanced section). The 'x' refers to which @Zx variable holds the filename to save to. Example: @Z5="milcvar.val"; @$5 @&x - Restore @Zx and @Nx values from a file in MBBSEXEC format This command will restore the values of all of the @Zx and @Nx variables from a file compatible with MBBSEXEC format (see MBBSEXEC - Advanced section). The 'x' refers to which @Zx variable holds the filename to restore from. Example: @Z5="milcvar.val"; @&5 @!x - Delete File This command will delete a file. The 'x' refers to which @Zx variable holds the filename to delete. Example: @Z5="milcvar.val"; @!5 @?x - Check for File Existence This command tests for the existence of a file. The filename ([d:][path]filename[.ext]) to test is in @Zx. The result is placed in @N0 (1=exists, 0=does not exist). Example: @Z5="d:\magnum\testfile.ext"; @?5 @b1(n0=1); The file does NOT exist! @c16 @p1 The file DOES exist! These four MILC commands (@$x, @&x, @!x, and @?x) can be used to pass the values of the @Zx and @Nx variables to MBBSEXEC with (see MBBSEXEC - Advanced Section). The @Nx variables in MSESSION correlate with the @TALLYx variables in MBBSEXEC. The @Zx variables in MSESSION correlate with the @STRINGx variables in MBBSEXEC. See the SAVE_DATA() and RESTORE_DATA() commands in the advanced section of MBBSEXEC. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-48 Customizing MAGNUM - Display Files/MILC Commands "Sysop Only" MILC commands: @$x, @&x, @!x, and @?x These four MILC commands (@$, @&x, @!x, and @?x) are available to the Sysop only. This means that any message in the message database wishing to utilize these commands must have the Sysop (ID: /0) as the originator of the message. All other display files may contain these commands since those files must have been created locally anyway (ie: external menus, help screens, HELLO?.*, SEC*.*, etc). These commands, as with all other MILC commands will have no effect if included in a file being viewed from the File section's "[A]ccess Arc/Zip file" function or "[R]ead Ascii File". MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-49 Advanced MILC Command Usage - Indirect Addressing Advanced MILC Command Usage - Indirect Addressing (Indexing) The MILC command language includes an advanced feature known among programmers as "indirect addressing" (or "indexing"). If you are a programmer, or if your company has programmers, this section might be best left to them. NOTE: Please have a thorough understanding of the MILC command language prior to using indirect addressing! Nearly every MILC command is of the format @Xn (where '@' is the MILC command character, 'X' is the command group, and 'n' is the command function or variable number). Indirect addressing eliminates the need to specify 'n' directly. By means of example, lets suppose you wanted to display the values of ALL of the @Ux variables, one per text line. Up until now, the only way to do this was as follows: 0 : @U0 1 : @U1 . . . 66 : @U66 The above would take 67 message lines (or 67 display file lines) to accomplish the task of displaying @Ux variable contents from @U0 through @U66. The following example demonstrates how to perform the same task with indirect addressing: @N5=0; @P0 @N5; : @U[N5] @N5=(N5+1); @B0(N5<67); Note that in the above statements, we've introduced brackets '[' and ']' after the @U variable. In the past, @U had to be followed by the number of which @U variable you wanted. With brackets, the contents of the brackets tell Magnum to get this number from the @N5 variable. The first time through the loop, @N5 contains 0 (zero), so @U[N5] would be identical to @U0. The second time through the loop, @N5 contains the value of 1, so @U[N5] would be identical to @U1, and so on. Note that there are two acceptible ways of indirect addressing. Assuming the value is in variable @N5 (indirect addressing ALWAYS references a @Nx variable), the following two statements are identical: @U[N5]; @U[5]; We chose to use the @U[N5] method above for your convenience. Our prefered method would be @U[5]. Keep in mind that the above examples used the @Ux variables with indirect addressing, however, idirect addressing can be used with any MILC variable that expects the command-group character to be followed by the variable number or command function. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-50 Customizing MAGNUM - Display Files/MILC Commands Advanced MILC Command Usage - Indirect Addressing EXCEPTIONS TO INDIRECT ADDRESSING: YOU CANNOT INDIRECTLY ADDRESS MILC VARIABLES WHICH: 1) Appear within parenthesis 2) Appear to the right of an = (assignment) sign. 3) The @Px MILC variable cannot be indirectly addressed 4) The @Ix@Zy statement: The @Zy portion cannot be indirectly addressed. The following demonstrates some correct and incorrect usage of indirect addressing: @U[12] CORRECT @B[17](0=0); CORRECT @N5=Z[3]; INCORRECT (brackets illegal on right of '=') @Z5=(Z[2]+Z4); INCORRECT (within parenthesis and right of '=') @\[14] CORRECT Indirect addressing comes in most handy when building jump tables. For example: 1 - Today's News 2 - Stock Quotes 3 - Online Shopper 0 - Quit, Return to BBS Choice (1,2,3,0) => @N5(0,3); @B[5]; @P1 - - - Today's News - - - . . . @C16 @P2 - - - Stock Quotes - - - . . . @C16 @P3 - - - Online Shopper - - - . . . @C16 @P0 @C16 The same rules of a terminating semicolon (;) still apply for those MILC command which require the terminating semicolon (ie: @B, @N, and @Z statements). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Customizing MAGNUM - Display Files/MILC Commands Page 4-51 Advanced MILC Command Usage - Enhanced Indirect Addressing Enhanced Indirect Addressing Indirect addressing was explained on the preceding pages. Now we'll introduce what we call "Enhanced Indirect Addressing". If you're familiar with the C programming language, you know about the ++ and -- operations on a variable (ie: x++, --x, etc). We've incorporated a similar operation in Enhanced Indirect Addressing. By way of example, here's how Enhanced Indirect Addressing works: @U[+5] -- Increments the contents of @N5 prior to processing the statement. If @N5 had the value 15, then this statement would be identical to the statements: @N5=(N5+1); @U16 @U[-5] -- Decrements the contents of @N5 prior to processing the statement. If @N5 had the value 15, then this statement would be identical to the statements: @N5=(N5-1); @U14 @U[5+] -- Increments the contents of @N5 AFTER processing the statement. If @N5 had the value 15, then this statement would be identical to the statemnts: @U15 @N5=(N5+1); @U[5-] -- Decrements the contents of @N5 AFTER processing the statement. If @N5 had the value 15, then this statement would be identical to the statements: @U15 @N5=(N5-1); Note that @U[+5] could also be denoted as @U[+N5]. The concept of the + and - symbols either prefixing or suffixing the value stems from the ++ and -- operations in the C programming language. The new, enhanced ability to increment/decrement the contents of the @Nx variable being referenced within brackets would replace the following: @N5=0; @P1 @U[5] @N5=(N5+1); @B1(N5<67); with: @N5=0; @P1 @U[5+] @B1(N5<67); and of course, both of the above methods are shorthand for: @U0 @U1 @U2 . . . @U66 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 4-52 Customizing MAGNUM - Display Files/MILC Commands Advanced MILC Command Usage - Enhanced Indirect Addressing The ability to increment/decrement the contents of the @Nx variable being referenced in brackets also has one additional feature - the ability to specify both a prefix and a suffix! For example: @N5=1; @U[+5+] would be the equivalent of: @N5=1; @N5=(N5+1); @U2 @N5=(N5+1); In either case, the value of @N5 would be 3 when complete. Other valid examples: @U[5] @U[5+] @U[5-] @U[+5] @U[-5] @U[+5+] @U[+5-] @U[-5-] @U[-5+] Of course, these are not limited to @Ux variables, nor is the bracket reference limited to 5 - we merely chose this for illustrative purposes. Here's one additional example which demonstrates how to display the entire character set using what you've just learned: @N5=0; @P0 @\[5+] @B0(N5<256); And as a friendly reminder, indirect addressing (the use of '[' and ']') is NOT available for MILC variables appearing within parenthesis or on the right side of an assignment (=) statement. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-1 Intro MAGNUM's sysop console (the parent process) - the program entitled MBBS, should be blown up to a full-size screen for this chapter. You've probably already guessed at certain portions of the display, but basically MAGNUM's sysop display shows you a brief summary of what is going on in the system and on each node. For instance, the date and time displayed above the [Node01] line is always accurate. On the same line, you will see numbers on the far right if/when someone is logged on. Assuming the 4-node version (node 4 is the conosle/local node), if there is a user on node 1 and 2 for example, you will see "1,2" (without the quotes). If you're logged on locally, you will see 4(x) where 'x' is the logical node you're on. If you log on locally with "* logon", you will see 4(4). However, if you logon with a logical node (ie: "logon 2") you will see 4(2). Note that on the same line as the "Node01" title, you will see "Magnum BBS (r) " followed by your serial#. The Sysop display console (the MBBS.EXE program) displays 3 sessions at a time. Intially, the sessions for Node01, Node02, and Node03 are displayed on the screen. To see other sessions, use the TOP command. In other words, if you have our 9-node version (8 comport + console), you could enter the command "4 TOP" (without quotes) and Node04 would be brought to the top of the display - sessions Node04, Node05 and Node06 would be displayed. In the 4-node version (3 comports + console), "2 TOP" and "1 TOP" are the only acceptable commands. The first line of each shows whether the line is ACTIVE (waiting for calls or announce only), or INACTIVE (shut down or not operating), or who is on. If you just started the MBBS.EXE program, the next 2 lines of each screen will be blank, otherwise, if someone is online, line 2 will show some brief info about them, while line 3 will show where they are in the system and what they're doing. If no one is on an active line, the system will show who was last on, when they called and how long they were on for. By the way, the "how long they were on for" (in minutes) will change to 0 (zero) if someone tried to call the board but didn't successfully log on since the last successful caller, or if carrier was dropped. The "Command => " prompt is where you interact with MAGNUM to do things like turn the bell on/off, force a user off, shutdown the bbs, turn on/off the printer, etc. You can only get to this prompt by hitting one of 11 keys: a digit (0 to 9) or an asterisk (*). If you press a digit, it should be the digit of the node you wish the command to apply to. If you press *, the command applies to all nodes (except local logon). IMPORTANT: When entering a command, MAGNUM assumes high-priority and DOES NOT process incomming calls or any other obligations until you have finished entering your command. Therefore, USE THE COMMAND PROMPT AS QUICKLY AS POSSIBLE!! If you hit a digit or * and walk away, you have effectively frozen your BBS - currently running sessions are not affected but no more incoming calls or events (ACE commands) will be processed! The remainder of this chapter will deal with the commands you can enter as sysop at MAGNUM's Sysop Command prompt. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-2 MAGNUM's Sysop Console The Bell, Forceoff, Switch and Info Commands x bell|nobell Sometimes the sound of bells can become rather annoying. MAGNUM sends a BEL character to the remote user when it doesn't like something, or when it needs to alert the remote user of something. This BEL is also echoed at the sysop console. To turn it off for, say Node01, you would enter: 1 NOBELL To turn it on, enter: 1 BELL Note that turning the bell on and off does not affect the remote user's end. The remote user will always hear the bell. x forceoff You can FORCE a user off anytime you wish. All this command does is emulate a dropped carrier on whatever node you use it on. The user could call back immediately if they wanted to. To force a user off of node 2, for example, you would enter the command: 2 forceoff The system will act as though the user dropped carrier (hung up), and reset itself for the next caller on that node. x switch You can snoop on any session in progress by switching to it. When a session starts (with the exception of a local logon), the session starts at your end as an icon. For example, if you wanted to snoop on the user on node 1, you would enter: 1 Switch This would blow up the icon into a window or full text screen (depending on how MSESSION.EXE is marked to start). You can also switch to that session by double clicking the mouse pointer on that session's icon. SNOOPING ON SOMEONE PERFORMING A FILE TRANSFER (ie: making their session the foreground process so that you can see what they're doing) WILL RESULT IN A TEMPORARY BOOST IN PRIORITY TO THAT FOREGROUND PROCESS! THIS CAN SLOW DOWN ALL OTHER SESSIONS! REMEMBER THAT ANYTIME YOU SNOOP ON A SESSION, IT WILL RECEIVE A TEMPORARY BOOST IN PRIORITY BY OS/2, THUS CAUSING A SLIGHT SLOWDOWN FOR ALL OTHER SESSIONS. FILE TRANSFER DOES LARGE BLOCK WRITES AND READS TO AND FROM YOUR MODEM (ie: 1K blocks) WHICH CAUSES TREMENDOUS SLOWDOWN IN PERFORMANCE OF THE OTHER SESSIONS IF YOU SNOOP ON SOMEONE DOING A FILE TRANSFER (make them the foreground process). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-3 The Bell, Forceoff, Switch and Info Commands BECAUSE OF THIS TEMPORARY BOOST IN PRIORITY FOR FOREGROUND PROCESSES, WE HAVE THROWN IN A DECREASE IN PRIORITY FOR THE LOCAL NODE (logon via console). THEREFORE, WHEN YOU LOGON LOCALLY (console), YOUR SESSION WILL BE SLOWED DOWN (purposely) IF OTHERS ARE ONLINE! x Info The INFO command shows information about NODEx. It shows whether the bell is on or off (beeping echoed to console), whether the printer is enabled or disabled, whether normal or announce-only mode is used. Also shown is the serial number and the node numbers of all active ports (nodes), the device name associated with NODEx and whether or not a SHUTDOWN is scheduled for node x. If a shutdown is scheduled for all nodes it will be shown here. As always, whenever you are executing a command, the parent "freezes" (won't respond to incoming calls) until the command is completed. In this case, a display is presented and you are prompted to strike a key to clear the display - the parent remains "frozen" until you clear the display by striking a key. Note that the display for the "info" command takes place on the bottom 6 lines of the display screen/window. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-4 MAGNUM's Sysop Console The "* auto" and "* noauto" commands "* auto" and "* noauto" * AUTO - Automatically switches to a session when a remote session is started (regardless of node). This command might be considered useful for those sysops running a single-node BBS, whereas those running a multi-node BBS might find this command to be disruptive. * NOAUTO - As before, only a local logon will be switched to automatically, all other nodes must be switched to by either the "x switch" command or by double clicking on the session's icon with the mouse pointer. This is the startup default. To make "* AUTO" the default, you can have it as an "immediate" command in your ACE file. Note: Refer to the chapter on ACE (automatic command execution) - Magnum's event handler. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-5 The level, print and lockout commands x level yyyy While someone is actively online, you can change their security level with this command. For example, if you wish to change the user on node 1 to a security level of 50, you would enter the following: 1 LEVEL 50 MAGNUM would then give you a message as to the success of the command. x print MAGNUM automatically keeps a log of activity for each node in a file called ACTIVITY.x (where x is the node number in which activity is being recorded). This file grows substantially with time so you'll want to back it up if desired and delete it from time to time. Note that if you view the activity log from MAGNUM's sysop menu when you're logged on, you will be viewing the log backwards (most recent activities first). You may elect to simultaneously log to your printer what is happening on a given node as well as to this activity-log file. To start doing this for node 1, for example, enter: 1 print To turn it off for node 1, enter: 1 noprint If running MAGNUM as a multinode system (more than 1 active node), and printing to the same printer for both nodes, you need to use the spooler. Be advised the spooler uses MUCH RAM MEMORY, and in some cases, there may not be enough left to run MAGNUM as ancticpated. This depends on how much RAM memory you have in your system to begin with. x lockout You can LOCK OUT any user currently online. For example, if you decide the user on node 2 is abusing the system, you can lock them out with: 2 lockout The user will be denied subsequent access. To prevent abusers from calling at all, consider running Magnum as a "closed" system. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-6 MAGNUM's Sysop Console The active, time, announce/normal, and logon commands x active|inactive If you have an active node running that you'd like to make inactive, or if you have an MBBSINIT.x file defined for a node but that node is currently not active, this command will let you toggle the current state of the node to/from active/inactive. For example, to make node 1 inactive, enter the command: 1 inactive To make node 2 an active node, enter the command: 2 active Note that the "inactive" command takes place immediately if there is no one online on that node at the time you issue the command, otherwise the command takes place after the current caller logs off. time+nnn | time-nnn You can increase or decrease the amount of time a user has left for their session with this command. nnn is the number of minutes you wish to increase or decrease their time by. For example, if you wish to increase the time for the user on node 1 by 20 minutes, enter the command: 1 time+20 If you wish to decrease the time for the user on node 2 by 10 minutes, enter the command: 2 time-10 Note that this command is processed by the minute. In other words, the effect of this command may not be realized for up to 1 minute. NOTE: Changing the user's time via the Sysop Utilities (user area) will not work if the user being changed is currently logged on. You MUST use the "x TIME+nnn" or "x TIME-nnn" commands for a user who's currently logged on. announce | normal This command changes a node from normal BBS operation to announce-only, and vice versa. If you wish to change node 1 from normal BBS operation to announce-only, simply enter the command: 1 announce Note that by doing so, MAGNUM will answer incoming calls as usual but will display the file ANNOUNCE.1 (for node 1, ANNOUNCE.2 for node 2, etc) to the caller and then hang up. MAGNUM will continue to be in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-7 The active, time, announce/normal, and logon commands announce only for whatever node you told it to announce to until you change it back with the following command: 1 normal Note that the ANNOUNCE.x file should not have any color or ANSI sequences in it since no one is allowed to log on, therefore, you don't know if your caller has color capability or not. The file(s) ANNOUNCE.x should be placed in the PROGRAM DIRECTORY. - - DO NOT SET YOUR LOCAL NODE AS ANNOUNCE-ONLY! Every time an ANNOUNCE.x is sent to the remote caller, Magnum logs this in a file called ANNOUNCE.LOG in your PROGRAM DIRectory. * logon As mentioned earlier, you can log on locally (without a modem) by entering the command: * LOGON Currently, you will need to have a MBBSINIT.4 file in order to do this. You can accomplish this by copying STARTUP.1 to STARTUP.4, then changing the NODE parm to 4 and recompiling with the MAKEMBBS.EXE program. If you have the 9-node version of Magnum, STARTUP.9 is your local node. Alternately, you may log on to any of the logical nodes locally with: * LOGON x Where 'x' is the node# of the logical node you wish to log on to. You will still be on physical node 4 (console for 4-node version) or node 9 (console for 9-node version), etc. With this alternate method, Magnum is simply using the MBBSINIT.x file for all of its information rather than the MBBSINIT.4 or MBBSINIT.9 file. Because each MBBSINIT.x files can be its own separate BBS (with its own databases by making the session directory unique from the other nodes), this method of logging on locally allows you to be online as though you were on node x. It's also a great way to test your MILC files if you have different display files for different nodes. Note that node 'x' does not have to be "active", nor do you have to wait until someone on the real node 'x' logs off. You may log on to node 'x' locally anytime. NOTE: In the MBBS.EXE display screen, on the far right of the same line as the date and time, MBBS will show you the node number(s) of the node(s) currently having a caller logged on. For example, if callers are on nodes 1 and 3, MBBS will show 1,3. If your console node is node 4 (4-node version) and you log onto node 4 (* LOGON), MBBS will show 1,3,4(4). The 4 (in the 4-node version) indicates console node, and the parenthesized number next to it shows logical node. If you logged on to node 2 locally (ie: * LOGON 2), then MBBS would show 1,3,4(2). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-8 MAGNUM's Sysop Console The endnow, end, shutdown and msg commands * endnow You can end MAGNUM BBS immediately by entering the command: * endnow This will cause MAGNUM to emulate a dropped carrier on all nodes currently in session, then finally end the program and return back to the OS/2 command line or to the OS/2 start programs menu. * end To shut down MAGNUM BBS after the last caller's session ends, enter the command: * end Note that if 2 or more people are online, MAGNUM will deactivate the comport of each line after each respective session ends, thus disallowing further calls. When the last user logs off, MAGNUM shuts down and returns you to the OS/2 command line or to the OS/2 start programs menu. x shutdown | * shutdown You can tell MAGNUM to shut down any or all nodes with the SHUTDOWN command. Simply enter the shutdown command followed by the time you wish MAGNUM to shut down that node (or all nodes). The time must be in 24-hour format. For example, assuming it is 2:00 PM now, and you wish to shut down MAGNUM at 2:15 PM, you would enter the command: * shutdown 14:15 MAGNUM would then send the following message to all users on any of the nodes: << System going down in 15 minutes >> MAGNUM will send the "system going down" messages every 5 minutes from this point until 5 minutes are left, then at 1 minute intervals. When the time is reached, MAGNUM shuts down all nodes and terminates itself regardless of who's online or what they're doing. Note that MAGNUM doesn't send any "system going down" messages until 30 minutes before shutdown is scheduled. It then sends another at 20 minutes, then 15, 10, 5, 4, 3, 2, and 1 minute remaining. Note that if there is less than 20 minutes to shutdown and no one is on a particular node, MAGNUM shuts down that node anyway. Instead of shutting down all nodes, you can shut down individual nodes by using the node number instead of the *. For example, you can shut down node 2 by entering: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-9 The endnow, end, shutdown and msg commands 2 shutdown 05:28 This will schedule node 2 to shutdown at 5:28 (AM). MAGNUM will send "system going down" messages to this node starting 30 minutes prior to shutdown. If no one is on the node within 10 minutes of shutdown, MAGNUM will shut the node down anyway. To reactivate a shut-down node, for example, node 2, enter the following: 2 active To cancel a shut-down in progress (ie: node 2 will be shut down in xx minutes), enter the following: 2 shutdown cancel This is a powerful command and will not pay any attention to what users are doing. When the shutdown time reaches it's scheduled time, all nodes (or the particular node) being shut down will emulate dropped carrier! x msg "string" | * msg "string" The MSG command sends a quick and dirty message from the console to any or all ports. "string" (without quotes) is the contents of your message. For example, to send a quick message to node 1, simply enter: 1 msg Please update your telephone number! To send a quick message to all nodes, simply enter: * msg I'm starting a group conference - please go to the GROUP CHAT MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-10 MAGNUM's Sysop Console miscellaneous commands If you're running MBBS as a fullscreen text app, or you've blown up it's window to full size, the commands we've just described above will appear on the bottom 5 lines of the MBBS display screen. These are the most commonly used commands. There are a few other commands which you'll probably use less often which we'll cover now. Although premature for you to understand the following commands, you should scan them over for now, then return here for a better understanding once you complete the chapter on ACE (automatic command execution) - Magnum's event handler. Executing another program from within MBBS You can execute another program from within MBBS.EXE by starting the command with the * character, and then providing the program name and it's parameters within doublequotes (the " character) followed by a comma and one of WAIT, NOWAIT or DETACH. For example: * "program.exe parms",WAIT This would run "program.exe" while MBBS WAITs for it to complete, then returns back to normal BBS operation. A program run with the WAIT parameter causes MBBS to save the present screen image, and halt all further MBBS execution (will not have any effect on currently running sessions) until the program completes - at which point the screen will be restored and normal BBS operation will resume. Running a program with the NOWAIT parameter causes the program you specify to run concurrently with MBBS - normal MBBS operation is resumed immediately and the present screen image is not saved. Any program started in such a fashion must NOT write to the screen (or stdin or stdout), or expect any input from the console (or keyboard). If the program you're running does write to the screen, you can redirect it's output with the > character. For example, to redirect all output for the program, you might enter a command such as: * "program.exe parms 1>nul 2>nul",WAIT which redirects stdout (handle=1) and stderr (handle=2) to nul (a nonexistent dummy file name used by OS/2). Just a simple redirection of ">nul" which was good enough for DOS (redirected stdout and stderr to nul) will not work with OS/2 - instead ">nul" to OS/2 means the same as "1>nul" which will only redirect stdout but not stderr. Running a program with the DETACH parameter is identical to running it with the WAIT parameter except that the program will continue to run even if MBBS terminates. The program can do screen I/O only via VioPopUp() calls. The "* REFRESH" command In the event you've run another program with the NOWAIT or DETACH parameter and forgot to reroute it's output, thus causing it to write to the screen, you can refresh the screen with this command - it won't be MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-11 miscellaneous commands the last screen but it will at least get rid of the output from the externally running program. The "* ACE INIT" command This command will cause MBBS to re-read the MBBS.ACE file, over-writing any ACE commands that were queued for timed execution. When this command is issued, any ACE "immediate" commands contained in the file will be ignored - this insures that duplicate copies of programs will not be started. All previously stored ACE commands will be purged prior to re-reading the MBBS.ACE file. The "x TOP" command Although we touched on this command earlier, this command will basically be used by those running our 9-node system (8 comports + console) or 17-node system (16 comports + console). Because MBBS only shows 3 consecutive nodes on the sysop display at any given time, you can bring any node to the top of the display with this command. For example, the command "5 TOP" will display nodes 5, 6 and 7 on the sysop console. In the 4-node version, "2 TOP" and "1 TOP" are the only acceptable commands. In the 2-node version, the TOP command is unavailable. In the 9-node version, "X TOP" can be issued where X is a value from 1 to 7. In the 17-node version, X can range from 1 to 15. In the 9-node and 17-node versions, Magnum will automatically change the top display node itself on an incoming call that is not already one of the 3 in the current display. For example, if your TOP node is 5 (ie: displaying node information for nodes 5, 6 and 7), and a caller calls on node 2, Magnum will internally issue a "1 TOP" command resulting in nodes 1, 2 and 3 being displayed. In other words, Magnum issues an "x top" command where 'x' is the lowest node number which would also include display of the new caller. The 17-node version allows the use of the TOP command when in condensed mode, whereas all other versions disregard the TOP command in condensed mode (see "* CONDENSE ON" and "* CONDENSE OFF" commands). The "* SYSBELL" command Sometimes it can become annoying to hear the sounds Magnum makes when a caller's session is about to be started. The "* SYSBELL OFF" command will deactivate these sounds, likewise, the "* SYSBELL ON" command will turn them back on again. Do not confuse this command with the NOBELL/BELL commands which apply to the session - SYSBELL only applies to the Sysop console (MBBS.EXE) whereas NOBELL applies to MSESSION.EXE. The "* HELP" command When running MBBS.EXE as a fullscreen text app (or as a maximized text window), the sysop commands appear at the bottom of your screen/window in the last 4 lines of display. However, there isn't room for all of the commands to appear in the last 4 lines, therefore, "* HELP" will display the next set of 4 lines summarizing additional commands. Each time you enter "* HELP" (or "x INFO"), the HELP display at the bottom MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-12 MAGNUM's Sysop Console miscellaneous commands will alternate. The "x BLOCKWRITE" command The "x BLOCKWRITE" command enables/disables block writes for node x. For example, the command "2 BLOCKWRITE ON" would enable blockwrites for node 2, while the command "2 BLOCKWRITE OFF" would disable blockwrites for node 2. The "* COLOR" command This command doesn't affect BBS operation, it simply sets the colors used by MBBS.EXE which you might rather use than the default colors. The syntax is "* COLOR UPDT MSG EXIT", where: UPDT is the color of the update information printed on the sysop console for the three nodes being currently displayed. MSG is the color of any messages printed just below the "Command =>" prompt. EXIT is the color Magnum will reset your screen to upon exit. The value of the colors for all three parms can be one of 1 to 7 or 9 to 15 according to the following color table: 0 - UNUSED 8 - UNUSED 1 - blue 9 - bright blue 2 - green 10 - bright green 3 - cyan 11 - bright cyan 4 - red 12 - bright red 5 - magenta 13 - bright magenta 6 - brown 14 - yellow 7 - white 15 - bright white For example, the command: * COLOR 11 12 7 would set the UPDATE color to 11 (bright cyan), the MSG color to 12 (bright red), and the EXIT color to 7 (white). The settings used in this example also happen to be the default color settings. As with all other default system settings, you can put this command as an 'immediate command' in your MBBS.ACE file with the parameters to match whatever colors you choose. The "* CONDENSE ON" and "* CONDENSE OFF" commands The condensed mode of operation is mainly for those using the 9-node version of Magnum BBS or higher. Although it will also work for the 4-node version. The "* CONDENSE ON" command tells MBBS to display only the state of all nodes (ie: ACTIVE, INACTIVE, who's on the node, etc). In other words, instead of each node having 3 text lines of display, MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-13 miscellaneous commands each node will only have 1 text line of display. The "* CONDENSE OFF" command returns MBBS to the default 3 text lines of display per node. The advantage of 1 text line per node is that you can see who's on all nodes without having to issue a "x TOP" command. The disadvantage is that you don't know what the users of each node are currently doing. This command is geared for the 9-node version of Magnum and higher. Users of the 4-node version will probably not have much use (if any) for this command. Users of the 17-node version can issue the "x TOP" command for consecutive display of any 9 nodes. The "* PRTY class level" and "* PRTY ?" commands The priority class and level of MBBS.EXE (the Magnum PARENT program) can be set with this command. Note the syntax uses the space character to delimit the parameters (no commas). The priority class can range from 1 to 4 where 1=Idle Time Class, 2=Regular Time Class, 3=Time Critical Class, and 4=Foreground Class. The level within the class can range from 0 to 31 where 0 is the lowest level within a class (lowest priority) and 31 is the highest level within a class. Unless you are a system administrator or other individual experienced in fine tuning systems with priority levels and classes, this should remain at Class 2, Level 0 (* PRTY 2 0). Note that you can query the current priority class and level with the command "* PRTY ?". NOTE: Do not confuse this command with the PRTY_CLASS and PRTY_LEVEL parameters in your STARTUP.x file(s). Those are for the priority classes and levels of MSESSION.EXE (individual user sessions). The "* PLAY x" command and Recording a Session for later playback This command is similar to the "* LOGON x" command but "plays back" a previously recorded sysop session. The 'x', although optional, is the node#, and if not supplied will default to the console node (node 2 in the 2-node version, 4 in the 4-node version, etc). To record a session for playback, use the "* LOGON x" command and log on as usual (you cannot record a session from any node other than the console node). Log on as ID //0 (sysop) and note the double slash instead of a single slash. When you've logged on this way, you'll get a message stating "Invalid ID" and a note that the session is being recorded. When re-prompted for your ID, proceed to log on as usual. Everything will be recorded to a file for later playback with the "* PLAY x" command. Note that the 'x' in the LOGON and the PLAY command determines which file number to record or play back. NOTE: When recording a session, DO NOT stop any displays with <Ctrl-X> or the spacebar character! DO NOT run external programs requiring anything other than command-line arguments (no interactive pgms). The purpose of recording a session is to automate packing of the databases with an MBBS 'ACE' command, where "* PLAY x" would be the ACE command. See the chapter on ACE (Automatic Command Execution - Magnum's Event Handler). The "x YELL" and "x NOYELL" commands Although Magnum abides by the Sysop paging hours in your STARTUP.x MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-14 MAGNUM's Sysop Console miscellaneous commands file(s), you can override this with the YELL and NOYELL commands (where 'x' is the node number). For example, to turn off the ability for a remote user to page the Sysop on node 2, issue the command "2 NOYELL". To turn on the ability to page the Sysop on node 2, issue the command "2 YELL". Note that when NOYELL is issued on a node, it disregards Sysop paging hours and dissallows the ability for the Sysop to be paged. When YELL is issued, Magnum abides by the Sysop Paging hours specified in the STARTUP.x file for node x. The "x ONHOOK" and "x OFFHOOK" commands You can send ONHOOK and OFFHOOK commands to your modem. By sending an OFFHOOK command, it's like physically lifting your telephone off the hook and letting it sit there (any callers will get a busy signal). If you issue an ONHOOK command, it's like hanging up the phone (the modem is ready to receive calls). NOTE: Unless you have an external modem with lights that indicate whether your modem is onhook or offhook, we suggest you avoid the use of these commands. The "* RMAIL node:userid" command This command starts the RMAIL process (Magnum-to-Magnum remote mail exchange) with another Magnum BBS system. Refer to the chapter on Magnum-to-Magnum Remote Mail. The "x CALLS MAIL" and "x CALLS ALL" commands The "x CALLS MAIL" command sets node x such that only MAIL accounts will be granted access to the system on node x. Any USER accounts will be denied access. Optionally, the file NOTMAIL.x in your PROGRAM DIRectory (if it exists) will be displayed to a USER prior to denying access when the node is in 'mail only' mode. The "x CALLS ALL" deactivates "mail only" mode. When this command is issued for node x, node x will accept ALL caller types (MAIL and/or USER). The "* LOGOCOLOR x" command where 'x' is a number ranging from 1 to 15. The color value is the same as the values of the * COLOR statement. This command changes the color of the logo appearing at the top of the screen. This command is used if the default color does not show up on monochrome screens. The "* FRAMECOLOR x" command where 'x' is a number ranging from 1 to 15. The color value is the same as the values of the * COLOR statement. This command changes the color of the frames appearing around the node displays. This command is used if the default color does not show up on monochrome screens. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems MAGNUM's Sysop Console Page 5-15 CHATting between SYSOP (you) and a USER via the Console To chat with a remote user, simply SWITCH to their session (make their session the foreground process). When their session is in the foreground, press your <F7> key and both you and the user will be placed in SYSCHAT mode (Sysop Chat with User). Note that if the user is entering a message at the time you press <F7>, the chat will be delayed until the user finishes message entery, otherwise chat will take effect at the very next system prompt the user gets. To end the chat, simply press your <F7> key again. Note that all text which transpires between you and the remote user during SYSCHAT will be logged to the SYSCHAT.LOG file in your SYSOUT directory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 5-16 MAGNUM's Sysop Console TEST Mode (Testing your modem) This command will rarely be used. However, setting up a BBS for the first time can be frustrating. BBS software must be able to interact with your particular modem. Sysops are not expected to be modem experts, nor should they have to be. Sometimes, due to the nature of BBS and modem relationships, problems will develop during initial setup. Therefore, we've included a TEST mode for any problems which may be encountered when setting up a new modem. The syntax of TEST mode is "x TEST". For example, to put the modem on node 1 into test mode, you'd enter the following command on the Sysop command line: 1 TEST Once in TEST mode, brief instructions will appear which are all self explanatory. Basically, you'll start with the /INIT command and watch for the digit 0 (zero) being displayed after each STARTUP string sent to your modem. If you don't get a 0 back from a particular string, it indicates a problem with that string. Contact Gilmore Systems for further information regarding TEST mode. CAUTIONS: - DO NOT USE THIS MODE TO DIAL OUT WITH. THE RESULTS WILL BE UNPREDICTABLE! - AS WITH ALL OTHER SYSOP COMMANDS, MBBS.EXE WILL REMAIN IN A "FROZEN" STATE UNTIL YOU ARE THROUGH WITH TEST MODE (ie: will not recognize incoming calls). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-1 The PROGRAM DIRECTORY Within the PROGRAM DIRECTORY, the following files should be found: MBBS.EXE - The main (parent) program for MAGNUM BBS. This is the program that you will start in order to start the BBS. MSESSION.EXE - The child program that MAGNUM (mbbs.exe) calls for each session. PUTFILES.EXE - The child program that MAGNUM (mbbs.exe) calls for sending files when a user chooses the [D]ownload option. GETFILES.EXE - The child program that MAGNUM (mbbs.exe) calls for receiving files when a user chooses the [U]pload option. NOTEs about GETFILES.EXE and PUTFILES.EXE: Monitoring of Carrier has been re-established for file xfers - this has caused some problems in the past (version 1.0x of Magnum, mainly on IBM PS/2 machines with EE) and has been removed ever since. If monitoring of carrier is causing a problem for you, you can remove (or implement) this monitoring of DCD (data carrier detect) by setting the following ENVIRONMENT variable PRIOR to starting Magnum (mbbs.exe) on the OS/2 command line (or in a .CMD file that starts Magnum): SET DCDXFR=FALSE (turns off monitoring of DCD for file xfers) SET DCDXFR=TRUE (turns on monitoring of DCD for file xfers) If the environment variable DCDXFR is not found (ie: not defined), the default is to turn ON monitoring of DCD for file xfers (just as though you've defined SET DCDXFR=TRUE). Also, for your convenience, any of the following parms are all acceptable: To turn OFF monitoring of DCD for file xfers: SET DCDXFR=FALSE or SET DCDXFR=OFF or SET DCDXFR=NO or SET DCDXFR=N or SET DCDXFR=0 To turn ON monitoring of DCD for file xfers: SET DCDXFR=TRUE or SET DCDXFR=ON or SET DCDXFR=YES or SET DCDXFR=Y or SET DCDXFR=1 MAKEMBBS.EXE - The configuration compiler/de-compiler. This is the program that compiles your STARTUP.x files into MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-2 Back to Display Files & Subdirectories The PROGRAM DIRECTORY MBBSINIT.x files, or de-compiles your MBBSINIT.x files into STARTUP.x files. MBBSEXEC.EXE - This is the MBBS executive progam utility for sysops which not only simplifies maintenance, but also provides a very powerful, flexible programming language with which the Sysop of a Magnum BBS can use to define his/her maintenance needs. RJEMONIT.EXE - This is a daemon process which monitors RJE jobs started by Magnum. A daemon process is a program which runs in the background continually until your computer is either shut off or rebooted. A daemon process cannot be selected or "switched to" because it's running as a detached process. A separate copy of RJEMONIT.EXE is invoked only once for each node. The original invokation happens only when the 1st user on any node chooses the [L]ist/Execute function of the RJE section, or the first time the @E1 command is encountered. Once it's started, Magnum knows it's running and will never start it again unless the system has been rebooted. RJEMONIT.EXE will be invoked once for each node, and only if the @E1 MILC command or the [L]ist/Execute function has been selected in the RJE menu for that node. The RJEMONIT.EXE program is responsible for updating the RJE database when RJE job(s) complete - regardless of whether the user is online, or even if your BBS system is running or not. STOPMBBS.EXE - These programs are used to immediately stop ALL actively & STOPRJE.EXE running copies of MBBS.EXE and LOCALBBS.EXE (LAN Local Logon Module) and their associated MSESSION.EXE programs; AND all actively running RJEMONIT.EXE programs. For more information on the use of these programs, execute the program without parms. KILLPROC.EXE - This program is used internally by Magnum, however, you may find this program of use to you too. For more information on the use of this program, execute it without parms. MBBSINIT.x - The output files that MAKEMBBS.EXE creates from your STARTUP.x files. No node can run without a matching MBBSINIT.x file, where x is the node number. STARTUP.x - The human-readable source file which will serve as input to the MAKEMBBS.EXE program. MAKEMBBS.EXE converts these files to MBBSINIT.x files. ANNOUNCE.x - A simple text file (where x is the node number the file will be used on). This file contains an announcement and is displayed when the node is in "announce-only" mode. Do not use any ANSI escape sequences or color in this file! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-3 The PROGRAM DIRECTORY MBBS.ACE - A text file containing Magnum ACE (Automatic Command Execution) commands. Read by MBBS.EXE upon startup. Commands in this file can be a combination of "immediate" (commands to be executed right away) and queued commands (commands to be stored for later, timed execution on certain days and times). ACE.LOG - Generated by MBBS.EXE - this file contains the log of any ACE commands which were executed by MBBS.EXE including the date and time of execution. UTILIZ.DAT - This file contains utilization information about your system. It will not exist until after your first logon. An external child (door) program is in the works which will process the data in this file. For those interested in the record layout of this file please contact us for further information. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-4 Back to Display Files & Subdirectories The SESSION DIRECTORY Within the SESSION DIRECTORY, the following files should be found: SPLITKEY.EXE - This program rebuilds *.KEY files from your USER.DAT (user database) file. The SPLITKEY.EXE program will reject all LastName's not starting with one of the following characters: - alphanumeric (A-Z, a-z, 0-9) - underscore ( _ ) character - dollar ( $ ) character If the last name of any record does not start with one of these characters, the record for this file will not be rebuilt into a key file, but the last name will change to ERRORxxxxx (where xxxxx is the ID of that user account). NOTE: If you change someone's LAST NAME, whether with MBBSEXEC.EXE or via the Sysop menu, you'll need to rerun SPLITKEY.EXE, however, you can save time by running it with the first initial of the user's last name (before & after). For example, if you change one of your user's last name from DOE to SMITH, you would run SPLITKEY twice as follows: SPLITKEY D SPLITKEY S This causes the SPLITKEY program to rebuild USER_D.KEY and USER_S.KEY files. AMMO.MAG - Refer to the chapter on Remote Mail. NOCHANGE.LST - The [E]nvironment section of the main menu (where users can change their system/personal paramters) is now configurable by the Sysop as to which parameters may/may not be changed. If you wish all parameters to be changeable (as before), then do nothing! Otherwise, create the file NOCHANGE.LST in your SESSION DIRectory. This file is an ASCII text file which contains the numbers (1 thru 24 in this release) of which parameters you do NOT want your users to be able to change! For example, if you don't want users to be able to change System compression type (choice 1) or their birthdate (choice 11), then the file NOCHANGE.LST would contain the two menu numbers as follows: 1 11 The format of the file is one menu number per text line. BADNAME.LST - This ASCII text file contains a list of UNallowable logon names - one name per line, no imbedded spaces. See the enclosed BADNAME.LST for an example. BADUPLD.LST - This ASCII text file contains a list of UNallowable filenames for upload - one name per line. Wildcards * and ? are acceptable. Note that a semicolon (;) starts a comment. In the event that a user tries to upload a file MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-5 The SESSION DIRECTORY who's filename matches one of those in this list, the upload will be dissallowed. If the match is followed by a comment (';' character), the comment will display, otherwise Magnum will generate a message to the user. An example BADUPLD.LST file might look like the following: *.EXE ; Please 'ARC' or 'ZIP' all uploads! *.COM *.LZH PMDIARY?.* ; IBM internal pgm - not public! PM-DIARY.* ; IBM internal pgm - not public! CMD.EXE ; License required to distribute! NOANSCHK.LST - Magnum checks your SESSION DIRectory for a file by the name of NOANSCHK.LST (which you optionally create with your text editor). If it finds it, it checks the file for filename extensions NOT to check for harmful ANSI escape sequences after a file upload. The file contents of of NOANSCHK.LST may look similar to the following: ARC ZIP LZH ZOO GIF BMP Bascially, the contents of the file are the extensions of filenames NOT to run an ANSI escape sequence check on. Because many compressed files (such as ARC and ZIP) can inadvertantly reproduce a harmful ANSI escape sequence to redefine a keyboard key when typed to the screen, it is almost meaningless to check a compressed file because once uncompressed into its individual members, this may not be the case. It's okay to check files with extensions of EXE and COM because they may contain embedded sequences, however, binary files can also inadvertantly reproduce one of these sequences. ANSI checking is mainly helpful for files containing text. The program which performs this checking is CHKANSI.EXE which is located in your EXTernal DIRectory. The format of the NOANSCHK.LST file is one entry per line of file extensions only (do not supply complete filenames or wildcards) - only the extension is checked for a match. COMPRESS.LST - Magnum checks your SESSION DIRectory for a file by the name of COMPRESS.LST (which you optionally create with your text editor). If it finds it, it incorporates the instructions within into the BBS. With COMPRESS.LST, you can support whatever file compression schemes you wish. Although .ARC and .ZIP formats are built in AND can be overriden with this file, some of the internal .ARC and .ZIP routines still remain, as these are used for MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-6 Back to Display Files & Subdirectories The SESSION DIRECTORY system-generated files (ie: compressed file or message listings... for these, you'll still need ARC2.EXE and PKZIP2.EXE in your EXTERNAL directory. However, you can support other file compression formats such as .LZH or .ZOO for example. To support other file formats, create a file called COMPRESS.LST in your SESSION DIRectory with your favorite text editor. The format of this ASCII file is as follows (via example): Definitions for various file compressions. Sample COMPRESS.LST file. Anything not starting with: . C= D= L= T= K= will be treated as a comment line (ignored). .ZIP: C=PKZIP2.EXE -u %s D=PKUNZIP2.EXE -o %s L=PKUNZIP2.EXE -v %s T=PKUNZIP2.EXE -t %s K=PKZIP2.EXE -zq %s .ARC: C=ARC2.EXE u %s D=ARC2.EXE x %s L=ARC2.EXE l %s T=ARC2.EXE t %s .ZOO: C=ZOO.EXE a %s D=ZOO.EXE x %s L=ZOO.EXE l %s .LZH: C=LH.EXE A %s D=LH.EXE X %s L=LH.EXE L %s T=LH.EXE T %s Note that the first nonspace character must begin with . (the period character), or C= or D= or L= or T= or K= in order for it to be a valid statement, otherwise the entire text line is ignored (treated as a comment line). The . character defines the file extension for that particular file compression method. Therefore, .LZH: for example, defines the external programs necessary to process files ending with extensions of .LZH (don't forget to end the extension with the : character). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-7 The SESSION DIRECTORY Following .LZH: (for example), are four statements. The first statement, beginning with the C= keyword, defines the program name and parameters for COMPRESSING a file. The %s needed in all definitions represents the file name of the .LZH file and will be substituted with the .LZH file name internally when Magnum processes the file. Similar definitions exist for the D= keyword (DECOMPRESS), L= (LIST Members), T= (TEST integrity), and K= (Add Comment). Note that in the above example, there is no T= statement for .ZOO file processing. Not that it doesn't exist, but the ZOO processing program we tested didn't have this capability. It's ok to leave out the T= keyword (or any other, but we haven't tested with any keywords left out other than T). Now then, the external compression/decompression program(s) must conform to the following specifications: - Must write their output to STDOUT when listing members of a compressed file. - Must reside in your EXTERNAL DIRectory (do not supply path names in the COMPRESS.LST file). - The %s parameter which represents the file Magnum will be working with, can appear anywhere on the parameter line to accomodate external programs requiring the file name to appear before (as opposed to after) any arguments. - If the external program supports HPFS long filenames, then your WORK DIRectories should all reside on an HPFS drive. Please note that Magnum itself does NOT support long filenames - this lack of support is currently necessary to accomodate FAT systems. Support for long filenames may appear in a future release. - If the external program supports adding a comment (K=) to the file, it must be able read this information from STDIN (Magnum will redirect this information from ZIPCMT.n, where n is node#). Note that in our example COMPRESS.LST file above, we provided definitions for .ARC and .ZIP formats. These definitions are optional because these formats are already built in. However, we provided these definitions to show you how you can override the built-in definitions for .ARC and .ZIP format. If you leave out a X= keyword (ie: C=, D=, L=, K=, T=) then Magnum will use its built-in definition. Note that system-generated files (compressed file or message listings or other RJE generated compressed file) will use the built-in definitions to create an .ARC or .ZIP file regardless of the definitions found in the COMPRESS.LST file. All other MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-8 Back to Display Files & Subdirectories The SESSION DIRECTORY BBS functions will use the definitions in COMPRESS.LST if it exists. You may define up to 10 different file compression formats. In our example above, we've defined 4. We could have left out .ZIP and .ARC, which still results in Magnum understanding 4 formats since .ARC and .ZIP are built in unless overridden in this file. In the above example, Magnum will recognize that files ending with .ARC, .ZIP, .LZH and .ZOO are compressed files. You can [A]ccess these files (from file menu) without even providing a file extension. If you upload a file TEST.LZH and Magnum finds a file by the name of TEST.ZIP (or TEST.ZOO or TEST.ARC), it will disallow the upload. It will allow TEST.DOC however because .DOC is not defined as a compressed file format. Please note that the support for any external file compression or decompression programs is completely optional, as is the existence of the COMPRESS.LST file itself. USER.KEY - This file is the USER database KEY file for the BBS. This file will not exist until your first logon. USER.DAT - This file is the USER database for the BBS. This file will not exist until your first logon. FILE.DAT - This file is the FILE database for the BBS. This file will not exist until files are added or uploaded to the BBS. MSG.DAT - This file is the MESSAGE database containing message header information. This file will not exist until messages are entered via the BBS. RJE.DAT - This file is the RJE database containing RJE record information on who ran what jobs when, status of jobs, etc. This file will not exist until your first logon. UTILIZ.DAT - The utilization database (optional) - refer to the TRACK_UTILIZATION keyword in your STARTUP.x file(s). MILC.SUB - Magnum now looks for the existence of a new file (optional) by the name of MILC.SUB in your SESSION DIRectory. If found, it is used to signal Magnum to substitute a specific character with another if found in a @Zx variable. For example, the MILC.SUB's file contents might look like the following: substitute ~ with " 126=34 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-9 The SESSION DIRECTORY substitute | with ^ 124=94 The way it works is a statement such as x=y is interpreted as "replace all characters with ASCII decimal value x with ASCII decimal value y". All lines starting with a non-digit are ignored (treated as a comment). In the above example, 126 is the ASCII decimal value for the tilde (~) character. 34 is the ASCII decimal value for the double quote (") character. The statement 126=34 tells Magnum to replace any occurrence of the tilde (~) character found in any @Zx string withe the double quote (") character. Thus, the statement: @Z1="this is a ~test~ string"; would be stored (or printed) as: this is a "test" string These automatic, nonreversible substitutions take place only when a @Zx MILC statement is referenced. Although this capability is powerful yet obscure, it does provide an easy way of performing certain things not possible before. For example, if you wanted to have double quotes within a string to pass as a command line argument to a program, this capability provides it. Before this capability existed there was no way to accomplish this task. QSECx.BBS - This file is a quick way of sending a message to a QSECx.SCR certain security level. When a user's security level matches x, the file will be displayed to that user after logon. The file will be sent to matching security levels only once. The next time they log on, the file will not be displayed. To send the contents of the file to all level 100 users for example, simply name the file QSEC100.BBS. ALL QSECx FILES ARE OPTIONAL!! SECx.BBS - Identical to QSECx.BBS but will display EVERY TIME a user SECx.SCR logs on who's security level matches x. ALL SECx FILES ARE OPTIONAL!! IDx.BBS - Similar to QSECx.BBS but x must match the user's ID (not IDx.SCR security level). For example, to send the file to the user who's ID matches 144, name the file ID144.BBS. Once the file is displayed to that user, the file will be deleted. ALL IDx FILES ARE OPTIONAL!! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-10 Back to Display Files & Subdirectories The BULLETIN DIRECTORY Within the BULLETIN DIRECTORY, the following files should be found: BULLETIN.BBS - This is the file which is displayed by MAGNUM when a user BULLETIN.SCR chooses to view the BULLETIN file. This file usually uses MILC commands to act as a menu to include other files or to branch to other areas of this file. Users are notified if the date and/or time of this file has changed since they're last logon. NEWSLTR.BBS - This is the file which is displayed by MAGNUM when a user NEWSLTR.SCR chooses to view the NEWSLETTER file. As with any other display file, it may contain MILC commands to form a menu QUESTION.BBS - This is the file which is displayed by MAGNUM when a user QUESTION.SCR chooses to view the QUESTIONAIRRE file. This file usually uses MILC commands to act as a menu, perform I/O and log user's answers to disk. A typical use might be for an online order system in which users place orders with their credit cards. QUESNEW.BBS - If you've configured MAGNUM such that the GET_QUESTION QUESNEW.SCR parm is Y, then the contents of this file is displayed. This file will typically have MILC commands which will perform I/O and log the user's answers to disk. This file will be presented only once to every user who calls for the first time. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-11 The MENU DIRECTORY Within the MENU DIRECTORY, the following files should be found. However, ALL FILES in this directory are OPTIONAL. IF NOT FOUND, MAGNUM builds it's own menus dynamically and displays that instead. MAINMENU.BBS - Create your own MAIN menu in this file. If the file MAINMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. FILEMENU.BBS - Create your own FILE menu in this file. If the file FILEMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. MSGMENU.BBS - Create your own MESSAGE menu in this file. If the file MSGMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. SYSMENU.BBS - Create your own SYSOP menu in this file. If the file SYSMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. RJEMENU.BBS - Create your own RJE menu in this file. If the file RJEMENU.SCR exists, it will override the dynamic menu MAGNUM builds and displays. NOTE: With the use of imbedded MILC commands, you can effectively create one menu file per section which will look different to every security level. You can even have it appear differently for a particular user! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-12 Back to Display Files & Subdirectories The HELP DIRECTORY Within the HELP DIRECTORY, the following files should be found. However, ALL FILES in this directory are OPTIONAL. IF NOT FOUND, MAGNUM simply sends the user the "Help not available" message. MAINHELP.BBS - This is the file which is displayed when a user chooses MAINHELP.SCR the HELP option for the MAIN menu. FILEHELP.BBS - This is the file which is displayed when a user chooses FILEHELP.SCR the HELP option for the FILE menu. MSGHELP.BBS - This is the file which is displayed when a user chooses MSGHELP.SCR the HELP option for the MESSAGE menu. SYSHELP.BBS - This is the file which is displayed when a user chooses SYSHELP.SCR the HELP option for the SYSOP menu. RJEHELP.BBS - This is the file which is displayed when a user chooses RJEHELP.SCR the HELP option for the RJE menu. NOTE: With the use of imbedded MILC commands, you can effectively create one HELP file per section which will look different to every security level. You can even have it appear differently for a particular user! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-13 The DISPLAY DIRECTORY Within the DISPLAY DIRECTORY, the following files should be found. However, ALL FILES in this directory are OPTIONAL. IF NOT FOUND, MAGNUM simply sends an error message to the console (if you are snooping on the session) - otherwise, the remote USER is not aware of anything different. Any error messages you see as a "snooping sysop" are to be taken as warnings only - the remote user never sees these warning messages. NOTE THAT ALL FILES LISTED BELOW CAN EXIST IN EITHER .BBS or .SCR FORMAT (or both). THE ONLY EXCEPTIONS TO THIS ARE: PRELOG.BBS, LOWBAUD.BBS, CLOSED.BBS, QUOTES.BBS and OPEN.BBS DO NOT CREATE ANY .SCR FILES FOR THE ABOVE 5 FILES!! HELLO1.BBS - Displayed after the user successfully logs on. HELLO2.BBS - Displayed after HELLO1.BBS HELLO3.BBS - Displayed after HELLO2.BBS NEWUSER.BBS - Displayed after logon IF this is the user's FIRST logon. BIRTHDAY.BBS - If you've configured MAGNUM to ask new users for their birth dates, MAGNUM compares their birthdate with the current date. If it matches, the contents of this file is displayed. GOODBYE.BBS - Displayed when the user logs off. PRELOG.BBS - Displays BEFORE the LOGIN: prompt. LOWBAUD.BBS - Displays if the user's baud rate is LOWER than the lowest acceptable baud rate you've defined in the STARTUP.x file CLOSED.BBS - Displays IF you're running a CLOSED BBS and the new user's name is not found in the USER database. OPEN.BBS - Displays IF you're running an OPEN BBS and the user's user's name is not found in the USER database. This is an ideal place to place present the user with some information about the BBS and ask them if they wish to continue to log on as a new user. You can terminate their session with MILC command @C17 if they do not wish to continue. QUOTES.BBS - Displays at logoff. The quote sent is equal to the number of times the caller has called modulus the number of quotes in the file. The file should have the folloing format: %50 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-14 Back to Display Files & Subdirectories The DISPLAY DIRECTORY %1 This is Quote #1 %2 This is Quote #2. Any quote can use as many lines as you want. %3 This is Quote #3. . . . %50 This is Quote #50. The way this file works is as follows: The very first line in the file is a %x where x is the number of quotes in the file. After that, every quote is numbered with %x where x ranges from 1 to x. There should be NO SPACES between the % character and the quote# (x). The % character should appear in column 1. 50 is the limit used in this example - your actual file can contain as many quotes as you wish. PREUP.BBS - Displayed prior to the user performing an upload. POSTUP.BBS - Displayed after the user performs an upload. PREDOWN.BBS - Displayed prior to the user performing a download. POSTDOWN.BBS - Displayed after the user performs a download. UDRATIO.BBS - Displayed when the user's upload/download ratio has been exceeded. PRELIST.BBS - Displayed prior to performing a LIST FILEs command. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-15 The EXTERNAL DIRECTORY The following are the files (programs, text, .cmd files, etc) which are called/displayed by MAGNUM: CMD.EXE - Called when the sysop wishes to drop to the OS/2 command interpreter from a remote location. NOTE: NOT INCLUDED WITH THE BBS PACKAGE. IS PART OF OS/2. YOU'LL NEED TO HAVE THIS IN YOUR PATH STATEMENT! ARC2.EXE - Called when the user wishes to create/view a .ARC file. NOTE: NOT INCLUDED WITH THE BBS PACKAGE BUT AVAILABLE FOR DOWNLOAD FROM GILMORE SYSTEM'S BBS. PKZIP2.EXE - Called when the user wishes to create a .ZIP file. PKUNZIP2.EXE - Called when the user wishes to view a .ZIP file. ZIPCMT.x - A text file (x=node number) which, if exists, gets placed into any uploaded .ZIP file as a "ZIP file comment". Useful for advertising your BBS, etc. Requires PKZIP2.EXE CHKANSI.EXE - Called after every upload, and after every message entered. Checks if the uploaded file or new message has any harmful ANSI escape sequences imbedded within which may redefine your (or another user's) keyboard when viewed. If harmful escape sequences are found, MAGNUM automatically locks the user out of the system and logs them off! Included with the package. CHILDREN.BBS - Menu for external programs (known as 'doors' on DOS CHILDREN.SCR BBS's). The way this works is that upon exit of displaying this file, the variable @Z0 should hold the program name (no path or drive, just program name), variable @Z1 should hold command line arguments to be passed to the child (if any), and @N0 should hold either 0 or 1 where 0=child handles local echo, 1=door handles local echo. Subject to change. See our example CHILDREN.BBS file (included). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-16 Back to Display Files & Subdirectories The RJE DIRECTORY When the [L]ist/Execut option of the RJE menu is chosen, the file RJELIST.BBS (or RJELIST.SCR) is displayed - this file is expected to be found in the RJE DIRECTORY. Any program started from this file, or any other display file (with the @E1 command), will be expected to be found in this subdirectory. Output files created by your RJE programs are usually ARC'd or ZIP'd and placed in the RJE RESULTS AREA (one of your file download areas) for download (placed there with ADDRJE.EXE). File naming convention used is Ux@y.ZIP - where x is the user's ID number, and y ranges from 0 to F (hex) - if there are already 16 files to the user's name, no more will be allowed. All files in this section are automatically private with the user's logon password (if the user's logon password exceeds 10 characters, only the first 10 characters are used as the password). Files created by the [M]ake selection of the [F]iles menu are set to expire the following day, or will be deleted as soon as the user successfully downloads it. If you'll be writing your own programs to run as RJE jobs, run ADDRJE.EXE without parms for instructions on its use. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-17 The MESSAGE SUBDIRECTORY Where message files go. Any messages which are a description of an available file for download, will have the same filename as the downloadable file. MSG DIRECTORY is the parent subdirectory, and there MUST be 26 subdirectory entries within this directory, named A to Z. (IE: \magnum\msg\a, \magnum\msg\b ... \magnum\msg\z). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-18 Back to Display Files & Subdirectories The WORK SUBDIRECTORY Temporary workspace to hold extracted members of .ARC or .ZIP files and other temporary workspace needs. IMPORTANT: The WORK directory MUST BE UNIQUE for each node!!! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Back to Display Files & Subdirectories Page 6-19 The SYSOUT SUBDIRECTORY ACTIVITY.x - These files (x=1 for node 1, x=2 for node 2, etc) will be created if they don't exist. They contain a summary of activity on the board for the node they represent. These ACTIVITY.x files can grow very large in a short period of time. Therefore, it's a good idea to periodically delete these ACTIVITY.x files from time to time in order to conserve available disk space. SYSCHAT.LOG - This file will be created the first time you SYSCHAT with someone (not to be confused with GROUP chat). It will be appended to with all subsequent SYSCHAT's. You may delete this file anytime it gets too large. This file holds the contents of your "chat" sessions. GRPCHAT.LOG - This file will be created the first time 2 users speak with each other via the Group Chat option. It will be appended to with all subsequent Group Chat's. You may delete this file anytime it gets too large but you must terminate MBBS first. This file holds the contents of all Group Chat's. *.R?? - Any questionairres you may have - anytime I/O is used to write to disk with the @Z or @N commands, the responses go to the same filename as what they're responding to, only with an extension of .R?? where ?? is the node number the user is on when they're responding to the file. For example, if a user on node 2 is responding to questions within the file QUESTION.BBS, the results will be placed in QUESTION.R02. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 6-20 Back to Display Files & Subdirectories The USER SUBDIRECTORY The USER subdirectory holds files specific to your users. For example, if you allow any of your users access to MILC commands @Zx or @Nx, they have the ability to create messages which can ask questions of the reader and log their answers to a file. Those 'answers' get logged to a file in the USER DIRectory under the same name as the message file. User NotePads are also kept in this subdirectory. Any user who's created one or more notes will have files in this subdirectory. The NotePad files have the following naming convention: IDxxxxx.NPT - NotePad Titles for User ID xxxxx IDxxxxx.Nnn - NotePad nn for User ID xxxxx (nn = 00 to 99) This is for your own information. The remote user is oblivious to Magnum's directory structure or file naming conventions. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-1 As a USER, either remote via modem, or local via the console, Magnum BBS software is fairly simple and self explanatory. All menus offer online help which you can display by choosing the [?] command. A help file will be displayed which you've created (or altered from the file we supply). We have not supplied a help file for the Sysop menu, but feel free to create your own. A few 'not-so-obvious' usages of the system are command chaining. Whether or not a user is using single-keystroke commands (hotkeys), command chaining (also known as command stacking on some systems) is available at ANY prompt. To use command chaining, simply begin your entry with the semicolon (;) character. For example, if you are in the Main Menu and wish to read all mail since the last logon, you would enter: ;M;R;S Not only does this save time but omits displaying the actual menus when commands are chained. Unlike other systems, command chaining MUST START WITH THE SEMICOLON (;) CHARACTER!! Another not-so-commonly-known trick is to stop the display of any text file simply by hitting the <Ctrl-X> key combination). This way a user is not forced to read through a file in its entirety if they do not want to. There is a command (see MILC) which you can imbed in the file to disable the ability to stop its display with <Ctrl-X>. One more shortcut you can use on the system is the entry of dates when responding to any date prompt. For example, regardless of whether your date setting is European or US date format, you can enter a date in either format (MM/DD/YYYY or DD.MM.YYYY). Your default dateformat setting is used by Magnum only for display purposes. Also, you needn't enter a 2-digit month, or a 2-digit day, or a 4-digit year. As a matter of fact, the year is optional! Magnum will assume the following about dates: If a month or day is entered as 1-digit, it will internally convert it to 2-digits (by adding a leading 0). If the year is omitted, the current year is assumed. If a 1-digit year is entered, the current decade is assumed. If a 2-digit year is entered, the current century is assumed. If a 3-digit year is entered, the current millenium is assumed. If a 4-digit year is entered, that year will be used. By way of example, the following are all valid ways of entering June 5, 1991 (assuming the current year is 1991): 06/05/1991 or 05.06.1991 06/05/991 05.06.991 06/05/91 05.06.91 06/05/1 05.06.1 06/05 05.06 06/5 5.06 6/05 05.6 6/5 5.6 6/5/1 5.6.1 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-2 Using Magnum BBS as a USER There are other combinations to represent the same date, however the above should provide a sufficient example. If the current year were 1991, and you wish to express June 5, 1990, you could enter 6/5/0 or 5.6.0 or 6/5/90 or 5.6.90. Magnum BBS will automatically inform users if new mail has arrived for them during the course of their online session if the mail is NEW as of this session (checked every 60 seconds). When in the [F]iles menu, users tend to look for a file such as ALLFILES.ARC or similar name. What they're really looking for is a compressed file (ARC or ZIP) which contains a list of all the available downloadable files on the BBS. Traditionally, most BBS systems offer this file, which is updated once per day. With Magnum, however, the user simply chooses the [M]ake selection - Magnum will "make" an ARC or ZIP file containing a list of all available files on the BBS according to the user's selection criteria. The user is guaranteed that the created 'filelist' will be accurate as of the moment it was created. The user has until midnight that night to download the file - it will be automatically marked for deletion after midnight and will no longer be available for download. The created filename is of the format Uxxxxx@y.ARC or Uxxxxx@y.ZIP depending on whether ARC or ZIP is the default compression type in the user's profile. The 'xxxxx' part of the filename is the user's ID number, and 'y' is the number of downloadable files the user created today. 'xxxxx' can be from 1 to 5 digits, and 'y' can be a hex number from 0 to F. In other words, a filename of U12@0.ARC is read as "User /12 filenumber 0". U5@B.ZIP is read as "User /5 filenumber 11". Files of this type are automatically placed in the RJE subdirectory and are password protected with the user's logon password. Make sure you allow your users download capability from the RJE directory. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-3 The MAIN MENU The MAIN MENU, like any other menu in the system is SYSOP configurable. The SYSOP can choose to have the menu appear however they want, whether it's built dynamically by Magnum (via your STARTUP definitions) or whether it's an externally displayed file. Therefore, we will use the definitions for the MAIN MENU (and all menu's for that matter) supplied in our supplied STARTUP files for the purposes of documentation. The MAIN MENU, as with any other menu on the system will appear differently for different users depending on their security level. For example, you, as SYSOP, should have the highest security level on the system... the [X] option in the main menu (Sysop use only) should be defined in your STARTUP files as being available to security levels matching your security level as SYSOP. Therefore, users with lower security levels will not even see the [X] option in the main menu. Likewise, users with matching or greater levels than those defined by the individual menu selections will see those selections only and not those requiring higher security levels. The MAIN MENU currently has 19 different menu selections. We'll present these menu options one at a time: MAINMENU_MSG: (menu selection M) This menu selection takes the user into the "Message Section" of the BBS where s/he will be presented with the Message Menu (see MESSAGE MENU later in this chapter). MAINMENU_FILE: (menu selection F) This menu selection takes the user into the "Files Section" of the BBS where s/he will be presented with the Files Menu (see FILES MENU later in this chapter). MAINMENU_RJE: (menu selection R) This selection takes the user into the "RJE Section" of the BBS where s/he will be presented with the RJE Menu (see RJE MENU later in this chapter). MAINMENU_BULLETIN: (menu selection B) This menu selection presents the user with the BULLETIN.BBS file (expected to be found in the BULLETIN directory) which you've created (or will create) with your text editor. See MILC commands in an earlier chapter for how to create menuing systems. Because BULLETIN.BBS is reported to a user as being changed if it's been modified since that last time the user viewed the BULLETIN.BBS file, it is important that anytime you change any of the "included" files brought up by this file (if any), that you change the date of this file as well - otherwise, the user will not be notified of an update to bulletins. What we do at Gilmore Systems, is to present the user with a choice of bulletins to read via the BULLETIN.BBS file, and next to each choice we have the date MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-4 Using Magnum BBS as a USER The MAIN MENU of last modification enclosed in parenthesis. MAINMENU_QUESTION: (menu selection Q) This menu selection presents the user with the QUESTION.BBS file (expected to be be found in the BULLETIN directory) which you've created (or will create) with your text editor. See MILC commands in an earlier chapter for how to create menuing systems. MAINMENU_COMMENT: (menu selection C) This menu selection allows the user to enter the line editor or the ANSI message editor in order to leave a private message to the sysop. Once the user answers the prompt of which editor they wish to use, they can then enter a Comment (message) which will automatically be addressed to the Sysop (ID: /0) and marked as private (regardless of whether private messages are allowed or not). Unlike entering a message to the sysop from the MESSAGE section, the COMMENT selection from the main menu does not prompt the user for any header information - the user is taken directly to the selected editor for message entry. If using the line editor, enter the word "/EXIT" (without quotes) on a line by itself. The main menu's [E]nvironment option also lets a user change their profile such that they can end message entry with a null line (two successive ENTER's). Up to 150 text lines are allowed for any message entry, however, if your system is running quite low on memory, it will inform the user of the maximum number of text lines it is able to use. By the way, "/EXIT" can be shortened to "/EXI" or "/EX" (all without quotes of course), and is case independent. MAINMENU_PAGESYS: (menu selection Y) This menu selection first checks to see whether the current time of day coincides with the Sysop's paging hours. If it does, AND the Sysop's BELL parameter is on (see Sysop console commands), then Magnum will audibly page the Sysop for 30 seconds. The user can terminate this paging earlier by pressing <Ctrl-X> at their terminal. If the Sysop wishes to "chat" with the user doing the paging, the sysop can switch to the user's session and press <F7>. If the Sysop has not pressed <F7> before the 30 second paging is over, the user is presented a message stating "Sysop not responding to page...". In the event the current time of day does not coincide with the Sysop's paging hours, the user is notified of the Sysop's paging hours. MAINMENU_WHO: (menu selection W) This menu selection will present the user with a list of users (by ID#) of all who are on the system, regardless of which computer (in a LAN environment) they're logged on from. MAINMENU_CHAT: (menu selection S) This menu selection allows the user to enter GROUP CHAT mode. Many Sysops disable this feature (assign a security level higher than any MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-5 The MAIN MENU user to this function) because of abuse potential (fowl language, etc), but many Sysops also enjoy having the feature enabled. As a Sysop, this is your prerogative. When a user chooses this menu selection, they will be placed in GROUP CHAT mode and can page others on the system and send them immediate one-line private messages. If two or more people enter GROUP CHAT mode, they can converse with each other simply by typing back and forth. While a user is typing, Magnum is collecting what they type - when they reach the end of a text line, automatic wordwrap will work the same was it does as if they were typing a message in the message section. Each time automatic wordwrap happens, the line that the user just finished typing (prior to automatic wordwrap) will be sent to all nodes. This process repeats until the user presses their ENTER key. The ENTER key merely sends the current line. The user can also enter commands while in GROUP CHAT mode. A command starts with the / (forward slash) character in column one. The following commands are supported: /HELP - presents the user with this list /EXIT - End chat. Return to BBS. /MSG x "message text" - Send private msg to node x. /NODE x - Page user on Node x. /PAGEON - Allows you to be paged by others. /PAGEOFF - Turns your pager off. /TIME - Shows current time and time remaining. /WHO - Shows who's on system and what they're doing (highest node # is *always* for local sysop). This command is limited to showing only those logged onto the same physical machine (unlike the [W]ho command from the main menu). As with all commands on a Magnum system, case is unimportant - uppercase, lowercase, or any combination of each are all the same to Magnum. As is the case for ending Message entry, ending GROUP CHAT can be accomplished by entering one of /EXIT, /EXI or /EX on a line by itself. MAINMENU_INITIAL: (menu selection I) Selection of this menu item redisplays the initial welcome screen by displaying the files HELLO1.BBS (or HELLO1.SCR) thru HELLO3.BBS (or HELLO3.SCR). If you have colorful ANSI graphics in these screens or some special announcements, some users may want to have another look at it and this menu selection enables them to do so without them having to call back just to see those screens again. MAINMENU_USERS: (menu selection U) This menu selection provides the user with a means of listing the users in your USER database. When a user chooses this menu selection, a prompt will be accompanied by an explanation of the various ways a search can be performed. For example, if the user enters the * character in response to the prompt, ALL users in the USER database will be displayed including the dates of their last call to the system. If the user enters one or more characters of a user's last name, a list of MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-6 Using Magnum BBS as a USER The MAIN MENU all users who's first one or more letters of their last name matching the entry will be displayed. If a user wanted to search by company name, they'd start with the \ character - for example, to search for those from IBM, they'd enter \IBM - this would result in matches for IBM, IBM Corp, etc. Note that the search will match the letters entered if it finds it ANYWHERE within a company name. Lastly, a user can cross-reference other users according to user interests. If a user wanted to search for others who's interests were OS/2 and/or MUSIC, they would enter ?OS/2 MUSIC in response to the search criteria. This would result in a match for all users with an interest in OS/2 or MUSIC. NOTE: If the GEO_PRIVACY parm in your STARTUP.x file(s) is set to 'Y', then geographic information about any users will be omitted. MAINMENU_PARMS: (menu selection E) This menu selection allows a user to change the parameters in their profile. Currently, 22 changeable parameters exist. A typical display may look something like the following: 1) Default System Compression Type: ZIP 2) End Message Entry with null line (line editor only): NO 3) Your "page" switch is: ON 4) Company: XYZ Corporation 5) Street2: 123 Anystreet 6) City: Anytown 7) State or Province: CA 8) Zip: 90067 9) Country: USA 10) Password (non shown for security purposes): ****** 11) BirthDate: 06/01/1955 12) Phone1: 213-555-1234 13) Phone2: 213-555-4321 14) Computer: IBM PS/2 model 80 15) Default File Xfer Protocol: None 16) ANSI color: yes 17) Display "More" prompt: yes 18) Erase "More" prompt: yes 19) Use Single Keystroke Commands (no C/R required): yes 20) Your areas of personal interest: : OS/2 PM COMMUNICATIONS 21) Lines per screen: 23 22) Date Format (US, Europe): U Enter # to change (1-22), 0=display static info, N=Next page, Q=quit => A user can change any of the above parameters by entering it's number. For example, to change ANSI color from yes to no, the user would enter 16. When prompted for ANSI color, the user would supply N (no). If the user wanted to see their permanent info, they could enter 0 at this point amd a display similar to the following would appear: User ID: "/10" Security Level: 20 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-7 The MAIN MENU First called on (mm/dd/yyyy): 12/27/1989 Last called on (mm/dd/yyyy): 01/07/1990 Last new files search (mm/dd/yyyy): 01/01/1980 File xfer CPS rate: 240 Download limit per week: 700 files or 70000 K-bytes Conferences available to you: ABCEFGH Number of times you called: 12 Minutes of connect time remaining for the week: 105 minutes Note that if a user chooses European date formats, all dates will be in the format DD.MM.YYYY and all prompts requiring a date will also expect the input to be in this format. US date formats are in the form of MM/DD/YYYY. If the user chooses N (for NEXT page), a display similar to the following will display: 23) Nulls to send after CR: 0 24) "List Files" preference: None Enter # to change (23- ), 0=display static info, P=prev page, Q=quit => MAINMENU_STATS: (menu selection V) This menu selection displays system statistics. A typical display might look like the following: MAGNUM BBS (r) (C)Copyright 1989 Gilmore Systems: Serial # 1989070000 Parent (System) Serial#: 1989070000 Magnum Version 5.00C4 OS/2 Version: 1.30 BBS Name: "Gilmore Systems Home of MAGNUM OS/2 BBS" BBS Started: July 14, 1989 Total calls this node (node 1): 11241 Sysop: Chuck B Gilmore Sysop Paging Hours: 00:00 to 23:59 BBS settings: Parity=N, Databits=8, Stopbits=1 Modem: USRobotics Dual Std DTE Initial: 19200 (locked) User Records: 2250 Message Records: 2015 File Records: 1022 RJE Records: 115 Last system restart: 10/17/1990 16:27:07.06 As you can see, the list describes the Sysop's modem and DTE rate, number of records in the databases, number of callers for the particular node, paging hours, etc. This enables users to get a summary of your BBS at a glance. MAINMENU_CHILD: (menu selection D) This menu option displays the file you created (or will create) with your text editor by the name of CHILDREN.BBS - the file is expected to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-8 Using Magnum BBS as a USER The MAIN MENU be found in your EXTERNAL directory. See MILC commands for creating menuing systems. See CHILDREN.BBS in Chapter 2 for a description of how to communicate to Magnum which program to run and how it is to be run. MAINMENU_NEWS: (menu selection N) The description of this menu selection is identical to the description given for MAINMENU_BULLETIN except that the filename which will be displayed is NEWSLTR.BBS (expected to be found in the BULLETIN directory). MAINMENU_GOODBYE: (menu selection G) This menu selection prompts the user as to whether they really want to end their session or not. If Yes, they are prompted as to whether they wish to leave a Comment to the Sysop prior to disconnecting (See the VERIFY_GOODBYE option in the STARTUP file). MAINMENU_EXPERT: (menu selection T) This menu selection is actually a toggle switch. It simply reverses expert mode. In other words, if the user has full (complete) menus, choosing this selection will put the user in Expert mode (no menus, just a 1-line prompt showing valid menu characters). If the user is already in Expert mode, choosing this menu selection will put the user back into full-menu mode. MAINMENU_HELP: (menu selection ?) This menu selection will display the MAINHELP.BBS (expected to be found in the HELP directory) if it exists. If this file does not exist, a "help not available" message will be sent to the user. If the file exists, the contents will be displayed to the user. MAINMENU_SYSOP: (menu selection X) This menu selection is usually set to the highest security level so that it is only visible and selectable by the Sysop. Choosing this menu selection allows the user to enter the Sysop Menu. See SYSOP MENU later in this chapter for more information. MAINMENU_OPT1: (menu selection 1) MAINMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file MAINOPT1.BBS or MAINOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-9 The MESSAGE MENU The Message Menu currently has 10 selections available: MSGMENU_QUIT: (menu selection Q) This menu selection quits the Message section, returning the user back to the Main menu (see MAIN MENU earlier in this chapter). MSGMENU_UPDT: (menu selection C) This menu selection allows the user to choose which message areas they want to work on. Note that Magnum will only allow users to choose message areas they are authorized to use. By choosing this selection, users can limit the areas such that only areas coinciding with their interests are applied. MSGMENU_READ: (menu selection R) This menu selection enters the "Read Messages Submenu", where the user specifies how and what they wish to read. The "Read Messages Submenu" looks like the following: B = Backwards Read (newest first) D = Date to start from M = Match Text R = by Reference # S = Since Last Read U = To/From User (or to/from you) V = View MY unread mail Q = Quit When choosing most of the options, you'll see a "Scanning" message. This message is followed by a dot (.) for every 100 messages scanned. Note that choosing suboptions D or S will update the user's "last read" message references numbers in their user profile. All other selections will have no effect on their "last read". The rest of the submenu is self explanatory. At the end of reading any message (other than a Receipt message generated by Magnum), an internal message disposition submenu is built dynamically and presented to the user. This disposition submenu can have any combination of the following: [A]gain (re-read message) [B]ackThread (Appears when this is a response to a previous message. Choosing this option will find and display the previous message. You must choose the [N]oMoreThread option to get out of BackThread mode). [C]ontinuous (perform continuous (nonstop) reading of messages. No message disposition submenu appears after messages. Continuous reading is for those who wish to capture all messages to a file. Continuous reading will be MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-10 Using Magnum BBS as a USER The MESSAGE MENU stopped if the user presses their <Ctrl-X> key combination). [E]dit (Appears if this message if from you, and it has not been read by the addressee yet. If the message is public, this option only appears if the message has not been read by anyone else. Choosing this option puts the message back into Magnum's line editor and allows you to edit the message). [F]orward (Appears if this message is to you. If you'd like someone else to receive a copy of this message, choosing this option will prompt you for that user's ID). [K]ill (delete message - appears only if message is to/from you, and Sysop allows users to delete messages). [N]ext (read next message) [O]rigin (Appears when this is a response to a previous message. Choosing this option will find the Origin, or original message that started this thread). [P]rivate (Appears if this message is a public message to/from you. Choosing this option changes the message from public to private). [P]ublic (Appears if this message is a private message to/from you. Choosing this option changes the message from private to public). [Q]uit (Quits the "Read Messages Submenu" and returns the user back to the "Message Menu"). [R]eply (enter a reply to this message) [T]hread (Appears when there is a response to this message. Choosing this option will find and display the response. You must choose the [N]oMoreThread option to get out of Thread mode). [V]iew (Appears only if the user viewing this message is the creator of the message. If this user is allowed access to MILC commands -in particular, @Zx and @Nx- where answers can be logged to a file, this option will show the user the answers to those questions). [+/-] (Pressing the '-' key causes Magnum to read messages in reverse chronological order. Pressing the '+' key causes Magnum to read messages in chronological order. This option will not appear when reading 'S'ince, or from 'D'ate options in the "read messages" submenu). Normally, the default choice will be [N]ext. Sometimes it will be [T]hread depending on whether you're reading sequentially or following a thread. In either case, the default choice will be denoted by parenthesis instead of brackets - for example (N)ext instead of [N]ext. When a default choice is indicated on the message disposition submenu, the user need only press their ENTER key to accept the default. NOTE: When [T]hread was previously chosen, and (T)hread is the default, Magnum will stay in this state until [N]oMoreThread is chosen! Note that 'H' is an option available only if logged on locally (Sysop MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-11 The MESSAGE MENU console). It does not show up as an option. The 'H' option, if chosen, will provide a HARDCOPY of the message and will prompt you for the filename or device name of where to print the hardcopy. When performing a hardcopy, note that any embedded MILC commands are printed as is (unprocessed). MSGMENU_SCAN: (menu selection S) In order to choose this option, a user must have chosen a default conference, or a group of default conferences with the MSGMENU_UPDT (menu selection C) option. By choosing this option, only the headers of the messages, but not the actual messages themselves, will be displayed. MSGMENU_ENTER: (menu selection E) This menu selection tells Magnum that the user wishes to enter a message. Magnum will respond to this selection with a series of prompts: Which Conference (? for list) => Who is this message to? (/ID#, ALL, SYSOP, ?=UserList, blank quits) => if the above is to /ID# or SYSOP, it will display: To "JOHN S DOE" (ENTER=Y) (Y/N) => as an example. if the above is to /ID# or SYSOP, and private messages are allowed on your system, the following will display: Is this a Private Messages (ENTER=N) (Y=yes, N=no)(Y/N)=> Subject => Expiration date (MM/DD/YYYY) or blank for None => Do you want a receipt for this message (ENTER=N) (Y/N) => Editor Type: A)nsi, L)ine => After the prompts have been answered, the user will be in the selected editor (line or ANSI) for message entry. The user may now enter their message (or perform an ASCII upload such that no text line exceeds 72 characters). As the user types their message, automatic wordwrap will take place at the end of each text line if necessary. * * * THE FOLLOWING TEXT IS FOR THE ANSI-EDITOR ONLY: * * * ---------------------------------------------- The ANSI editor is self explanatory - all commands are at the top of the user's screen during message entry on lines 1-9. The user can enter up to 150 lines of message text. The text entry "window" is on lines 10-22 meaning the most current 13 lines of text are visible at any given time. A copy of the ANSI-EDITOR message entry screen is as follows: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-12 Using Magnum BBS as a USER The MESSAGE MENU * * ANSI SCREEN CONTROLS IN EFFECT * * | Ctrl-Key Combinations: /\ //\\ | K=End (save) | T=Type Msg Ctrl-W Ctrl-R | Y=Delete Line| X=Play Msg < Ctrl-A Ctrl-D > << Ctrl-Q Ctrl-E >> | G=Delete Char| B=Ins Char Ctrl-Z Ctrl-F | L=Abort Msg | O=Search \/ \\// | V=Insert Line| U=Srch/Repl Hit <ESC><ESC> for options. Max 150 lines| I=TAB | N=Goto Lin# Lines 1-13 ------------------------------------------------------------------------ _ ------------------------------------------------------------------------ The above sample entry screen is self-explanatory. However, a couple of clarifications are warranted. Firstly, the <ESC><ESC> option (meaning to press your <ESC> key twice in succession, will present you with an options menu. This options menu will allow you to view the message header Magnum will be using in your message. If you're responding to a message, you'll be allowed to re-read the message you're responding to, and "quote" text lines from that message to be brought into your message. Automatic wordwrap and page (screen) scroll is in effect when appropriate. Depending on whether you're creating a new message from scratch or responding to another message, other options which may appear in the options menu are 'RePlay Original Message', 'ReRead Original Message with Marking Facilities', and 'NotePad Facilities'. See the chapter entitled "NotePad Facility" for more information on using the NotePad in conjunction with messages. IF YOU'RE LOGGED ON LOCALLY: You can use your Ins, Del, PgUp, PgDn, Home, End and arrow/cursor keys in addition to the <Ctrl-key> combinations defined on top of the message entry screen. * * * THE FOLLOWING TEXT IS FOR THE LINE-EDITOR ONLY: * * * ---------------------------------------------- If using the line editor, message entry is exited by entering one of the following (case independent) on a line by itself starting in column 1: /EXIT /EXI /EX MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-13 The MESSAGE MENU Note that a user could also exit message entry by entering 2 consecutive CR's (press ENTER twice in a row, causing a NUL line) if they went into their [E]nvironment (from Main Menu) and changed #2 to YES. Once a user has exited message entry, another submenu will appear as follows: Edit Commands: [S]ave, [T]ype, [D]elete, [I]nsert, [C]ontinue, [A]bort, [E]dit line, [R]eplace line, [G]o The [S]ave option saves the message and prompts for CC (Carbon Copies) if the message is public and to an individual user. The [T]ype option simply redisplays what's been entered so far to the user's screen. The [D]elete option allows the user to delete a line or a block of lines. The [I]nsert option allows the user to insert a new line inbetween 2 existing lines. The [C]ontinue option places the user back in message entry mode from the point they left off at (last or highest line# they've entered). The [A]bort option aborts message entry altogether but first prompts the user as to whether an abort is their real intention or not. The [E]dit line option allows a user to change any character(s) or word(s) in a line to any other character(s) or word(s) in a line. The [R]eplace line option allows the user to replace an existing line with new text. The [G]o option allows a user to view their message exactly the way any recipient (reader) of the message would see it - including processing of MILC commands. NOTE: When the [S]ave option is chosen, Magnum runs CHKANSI.EXE (in your EXTERNAL directory) to check the message for harmful ANSI escape sequences. If an ANSI escape sequence is found which can redefine a key on the keyboard (it can do this when someone else remotely reads the message on their keyboard), then Magnum will automatically delete the message, lock the user out of the system, and hang up. This is a built-in security precaution which can be removed by simply deleting (or renaming) the CHKANSI.EXE program in the EXTERNAL directory. In the event of a user lockout, Magnum will create a message to the Sysop about the lockout. MSGMENU_KILL: (menu selection D) This option prompts the user for the Reference # (11 characters) of the message s/he wishes to delete. Magnum then checks to make sure that the message matching this reference # is either to or from the user - if it is, Magnum deletes the message, otherwise the deletion is disallowed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-14 Using Magnum BBS as a USER The MESSAGE MENU MSGMENU_SRCH: (menu selection T) This option prompts the user for a string of text. Magnum then searches the message database (only areas authorized to the user) for this text string within the SUBJECT descriptions of the messages. Magnum then displays the headers (only) of the messages matching the search. MSGMENU_CHECK: (menu selection P) This option is identical to the "Check Your Mail? (Y/N) => " prompt which appears after a user logs on (just before displaying the main menu). It simply checks the message database for any mail addressed to you which you have not yet read. MSGMENU_GOODBYE: (menu selection G) This menu selection prompts the user as to whether they really want to end their session or not. If Yes, they are prompted as to whether they wish to leave a Comment to the Sysop prior to disconnecting (see the VERIFY_GOODBYE option in the STARTUP file). MSGMENU_HELP: (menu selection ?) This menu selection will display the MSGHELP.BBS (expected to be found in the HELP directory) if it exists. If this file does not exist, a "help not available" message will be sent to the user. If the file exists, the contents will be displayed to the user. MSGMENU_OPT1: (menu selection 1) MSGMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file MSGOPT1.BBS or MSGOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. MSGMENU_BASE: (menu selection M) This menu selection is for those who've purchased [and installed] our 'Extended MessageBase' module. If you're not using this module, you should raise the security level of this menu option such that it does not appear on any user's screen. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-15 The FILES MENU The Files Section of Magnum provides some powerful features. Before we get into the menu definitions, let's start with a brief explanation of some of the unique built-in features. Firstly, Magnum assigns a number (#nnnnn) to every file in your file database(s). This #nnnn is the record number of any particular file in the file listings. At any prompt within the file section which requests a filename, you may provide the #nnnnn instead (start with the # character). The #nnnnn number method is *extremely* fast! Note however, that #nnnnn numbers will change after any time you perform a pack of the file database(s). Magnum's file section also has the ability to 'mark' files for download. When the remote user performs a file listing (and their MORE prompt is set to come on after every screenfull), part of the MORE prompt is the [U]tils selection. By choosing [U]tils, the user can 'mark' the file for download, 'view' the file and members within if it's a compressed file, 'read' the file if an ASCII text file, obtain 'info' on the file, etc, without losing their place in the file listings. When 'D'ownload is finally chosen from the files menu, marked files will automatically be placed on the user's download list (s/he needn't re-enter them), but will be given a chance to view and/or modify the marked files list prior to actually downloading. Note that system-created files such as a compressed file listing will automatically be placed on the user's download list as a 'marked' file. Any user-specific files generated by the system are automatically placed on the user's download list at logon time if such files exist and were not downloaded. Now for the menu selections of the File Section: FILEMENU_QUIT: (menu selection Q) This selection exits the FILE section and returns the user to the MAIN menu of the BBS. FILEMENU_INFO: (menu selection I) This selection displays information on a file. An example File Info follows: Filename: MAGCOM.ZIP File Area: E (This month's OS/2 uploads) Uploaded with YMODEM-G protocol Uploaded on 01/01/1990 at 06:41 Size is 80896 bytes File was downloaded 35 times Date of last access or download was 01/08/1990 Estimated download time: 5 minutes 24 seconds Brief (1-line) description: MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem Detailed Description Exists. Would you like to view it? (Y/N) => The "Estimated download time" will vary from user to user. Because MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-16 Using Magnum BBS as a USER The FILES MENU Magnum stores each user's last CPS (file transfer rate), it uses that figure to determine how long it will take to download any other file on the system. If the caller calls back at a different baud rate, Magnum will adjust the user's stored CPS accordingly. All downloadable files have brief (1-line) descriptions associated with them. Some files have a detailed description associated with them. If you display [I]nfo on a file with a detailed description, Magnum will prompt you as to whether you'd like to view the detailed description. The detailed description can be up to 150 lines of text in length. If a file has a detailed description associated with it, the file will show up in the file listings as having a '+' character in column 1 just before the file's date. FILEMENU_LIST: (menu selection L) This selection will list all available files on the board (which the user's security level permits him/her to know about). Files which are password protected will not show up in the listings if the Sysop has configured the STARTUP for that node not to show password protected files. Each file listed takes up 2 text lines plus a blank line separating it from the next file. When choosing the [L]ist option, the following prompt will appear: Area(s) to list (? for help, blank to quit) => Note that prior to displaying this prompt, if the file PREDOWN.BBS exists, it will be displayed to the user prior to sending this prompt. This prompt requires the user to press their ENTER key after answering their prompt because it is not limited to a single-keystroke. By responding with the ? character, Magnum will list all available file areas authorized to be listed to the user. File areas are labeled from A to Z. The + or * character tells Magnum to list ALL areas authorized to be listed to the user. An example of a file appearing in a file listing follows (note that if the file had an expiration date, it would be displayed after the file size): + 01/01/1990 MAGCOM.ZIP 80896 DLs: 45 #204 MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem If a + character appears in column 1 (just before the file date), it signifies that a detailed description (up to 150 text lines) exists, which can be viewed by choosing the [I]nfo option. The rest the file description in a list command shows the date of upload, filename, filesize, it's expiration date (if any), number of DownLoads, the file number, and a one-line description of the file. This information is shown for every file appearing in a file List command. If a user wanted to list more than one file area at a time (but not all areas), they would enter the areas pertaining only to what they wanted to see. For example, if the user wanted to list just areas C, H, K and L, they'd respond to the following prompt as follows: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-17 The FILES MENU -> Note that the file number (#204 in this example) can be used in -> response to any prompt requiring a file name, instead of the file -> name (answer the prompt with #204, not 204). Note that file numbers -> will change after anytime you perform a 'pack' of the file database. Area(s) to list (? for help, blank to quit) => CHKL Note that responses of "C,H,K,L" and "C H K L" (without the quotes of course), are also valid responses. Only 26 characters are allowed in response to this prompt - therefore, any commas (,) or spaces ( ) imbedded in the user responses are extraneous and unncessary. NOTE: When listing files by area, Magnum searches the DISPLAY DIRectory for a matching FDIR_x.BBS (or FDIR_x.SCR) file, where 'x' is the same letter as that of the file area about to be displayed. For example, if the user replied to the above prompt with EHK, then Magnum would first display FDIR_E.BBS (if it exists) prior to displaying the files in area E, then FDIR_H.BBS (if it exists) prior to displaying the files in area H, then FDIR_K.BBS (if its exists) prior to displaying the files in area K. FOR USERS OF THE 'EXTENDED FILEBASE' MODULE: When in an 'extended' FileBase [a FileBase other than 0 (main)], Magnum searches the DISPLAY DIRectory for a matching FDIRcnnn.BBS (or FDIRcnnn.SCR) where 'c' is the File Area (A-Z) of FileBase nnn (where nnn can be 001 to 255). Note that nnn must ALWAYS be 3 digits. If the matching file exists, Magnum displays it prior to listing the files in that area. For example, if the user is in FileBase 3 and wishes to list the files in area C of that FileBase, then Magnum will search for FDIRC003.BBS and display it prior to listing the files in area C of FileBase 3 if found. If not found, Magnum will simply go ahead and display the files in area C of FileBase 3. If logged on locally, or if snooping on a remote session, you'll see a message something like << File FDIRC003.BBS Not Found >> on your console (this will not show up on the remote user's end. Also, in response to any filename prompt, if using the Extended FileBase, a user may supply a filename any of four ways: FILENAME.EXT FILENAME.EXE:base #nnnnn #nnnnn:base Note that if they append the :base (ie: "filename.ext:2" for the file "filename.ext" in filebase 2), Magnum will switch to filebase 2 in order to access the file. File can be "marked" from any combination of FileBases. FILEMENU_DL: (menu selection D) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-18 Using Magnum BBS as a USER The FILES MENU This selection allows a user to download one or more files from the BBS. If the user has not selected a default file transfer protocol (via [E]nvironment selection from main menu), the user will be prompted to choose a transfer protocol for this download: Single: X=Xmodem, C=Xmodem-CRC, 1=Xmodem-1K Batch: Y=Ymodem, G=Ymodem-G, Z=Zmodem, Q=Quit Transfer protocol (X,C,1,Y,G,Z,Q) => Once a download protocol has been established (note that Ymodem-G is dissallowed by Magnum if the user has not made an error-correcting modem connection - ie: MNP, ARQ, etc), the user will be prompted for the filename(s) of the file(s) s/he wishes to download. If the file transfer protocol chosen is a Single-file protocol, only one filename will be accepted. If it's a Batch protocol, up to 9 filenames will be accepted. When the user supplies a filename, Magnum makes sure the file exists in it's file database - if it does, Magnum displays the size of the file and estimated download time of the transfer. If it does not exist, Magnum informs the user of this. If the user supplied a file extension of .ARC when it should've been an extension of .ZIP (or vice versa), Magnum corrects the entry and informs the user. Magnum will not allow the same filename to be entered twice in any given Batch download (just in case the user forgot that s/he already chose the file for download). Magnum will inform the user to start the transfer at their end once the filename(s) for download have been completed. The user must refer to their communications program's documentation for how to invoke a file transfer with their software. Some communications programs such as our MAGCOM program will automatically start a Zmodem file download - no interaction with the user is required (not applicable to MAGCOM version 1.0). Zmodem Crash Recovery is supported by Magnum on aborted downloads. When the file transfer is over, Magnum informs the user their CPS (characters per second transfer rate) if successful, otherwise Magnum will display a "Xfer Failed or Cancelled" message. FILEMENU_UL: (menu selection U) This file selection allows a user to upload a file to the BBS. The user will be presented the following series of prompts: Filename you will upload? (blank quits) => Not that prior to displaying this prompt, if the file PREUP.BBS exists, it will be displayed to the user prior to sending this prompt. At this point, the user will enter a filename for upload. Magnum then checks to see if the file exists in the database. If it does, the upload will be disallowed. Magnum will also check to see that the filename is not CMD.EXE, COMMAND.COM, or a device name - if it is, the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-19 The FILES MENU upload is disallowed. Magnum also checks to see that the filename does not contain special characters (ie: <, >, |, etc) and that the filename extension does not exceed 3 characters (to the right of the . character), and that the filename does not exceed 12 characters (including the . character). Magnum also searches BADUPLD.LST in your SESSION DIRectory (if it exists) to make sure it's not in the bad upload list (see BADUPLD.LST in the description of files in the SESSION DIRectory). Once Magnum has determined that the filename supplied is a valid upload filename, it will prompt the user for an upload protocol (unless the user has a default protocol selected in their environment). Note that Magnum only allows 1 file to be uploaded at any given time even if the upload protocol being used for the transfer is a Batch protocol. Next, Magnum will prompt the user for a one-line description of the file: Please enter a one-line description of the file: Next, Magnum will prompt the user as to whether the file should be password protected: Do you want this file password protected? (Y/N) => Next, Magnum will prompt the user for an expiration date: Do you want an expiration date for this file? (Y/N) => If the user selects Y, an expiration date prompt will appear, and the file will be deleted as of 00:00 on the expiration date. Next, if the user is allowed to upload to more than one file area, the following prompt will appear: Save file to which area? (? for list) => When the user answers this prompt, Magnum will display how many bytes are available on the upload disk drive containing the directory which will house the upload. Next, Magnum will prompt the user as to whether they'd like to leave a detailed description of the file: Would you like to leave a more detailed description of the file in message form? (Y/N) => If the user answers with Y, Magnum will invoke the line editor for the user to enter up to 150 text lines describing additional information about the file. Next, Magnum informs the user that it's ready to receive the file - it tells the user the filename and protocol it expects. Note that if MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-20 Using Magnum BBS as a USER The FILES MENU you're logged on locally (console), Magnum will prompt you for the source filename for a local copy. Once the transfer completes successfully, Magnum checks the file by calling the CHKANSI.EXE program - if it finds any ANSI escape sequences which redefine a keyboard key, it locks the user out of the system and disconnects. If the check is successful (no harmful escape sequences found), Magnum then checks to see if the uploaded filename is a .ZIP file - if it is, it checks to see if the file ZIPCMT.x exists (x=node number user is on) - if it exists, it adds the contents of that file to the .ZIP file as a ZIP comment. Magnum then adds the file entry to the database and displays the user's CPS transfer rate and compensates the user (if defined) with time spent for the upload, and gives the user credit for the upload. NOTE: In the event of Magnum locking out a user due to an upload containing harmful ANSI escape characters which will redefine keyboard key(s), Magnum will generate a message to the Sysop about this action. Because compressed files (ARC, ZIP) can sometimes reproduce this ANSI pattern, CHKANSI.EXE will lock the user out of the system even though there may not be any ANSI escape sequences to redefine the keyboard when the file is uncompressed. -> If you wish to disable this automatic checking of ARC, ZIP or -> files with other extensions, see the description of NOANSCHK.LST -> in the chapter entitled "Back to Display Files & Subdirectories", -> in the "SESSION Directory" section. If the uploaded file has an extension of .ARC or .ZIP, Magnum performs an integrity check on the file. If the integrity check fails, Magnum automatically deletes the file and no upload credit is acknowledged. FILEMENU_NEW: (menu selection N) This menu selection is identical to the [L]ist selection except that it only lists files since the last time the user selected the [N]ew files selection. NOTE that Magnum stores 27 separate dates for this selection for each user. It stores the date this selection was last used for each of the 26 different file areas (A to Z), and for the + (all files) selection. The prompt also gives the user a chance to override the default date. When [N]ew Files is selected, the following prompt appears: Which area (A-Z, + for all, ? for list, blank to quit) => Once the user enters this prompt, another prompt appears which will look similar to the following: Enter date MM/DD/YYYY (default = 01/08/1990) => Note that if the user has chosen [E]uropean date formats, the MM/DD/YYYY would appear as DD.MM.YYYY to the user. This applies to all date prompts on the system. If the user supplies a date in response to this prompt, that date is checked and will be used instead, otherwise, if the user simply presses ENTER, the default date displayed within parenthesis MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-21 The FILES MENU will be used instead. The listing which will appear after answering this prompt will have the same format as that used by the [L]ist Files menu selection. FILEMENU_SRCH: (menu selection T) This menu selection allows the user to perform a text search of files on the board. The text search searches both the filenames and descriptions in it's search. When this menu selection is chosen, the following prompt appears: Which area to search (A-Z, + for all, ? for list, blank to quit) => Once the user answers this prompt with one of A-Z or +, the following prompt will appear: Text to search for (blank quits) => Assuming the user supplied a non-blank answer to the prompt, the next prompt will appear: Files newer than (MM/DD/YYYY) (ENTER=01/01/1980) => The user can either accept the default date by pressing ENTER, or supply a different date. Once this prompt has been answered, Magnum will search the files database and display (in [L]ist Files format), a list of all files (if any) it finds matching the text supplied by the user. Both file description and filename fields are searched for a match. Note that the search is case independent, meaning that uppercase/lowercase is not an issue (ie: Graphics, graphics, and GRAPHICS are identical as far as Magnum is concerened). Note that any matches in a filename will result in the 'matching' portion of that filename being displayed in lowercase. Any matches in a file description will be bracketed (within [ and ] characters). At the end of the list of files matching the search criteria (if any), Magnum displays the "Press ENTER to continue ..." prompt. FILEMENU_STATS: (menu selection S) This menu selection presents the user with statistics on their upload/downloads performed both for the period and since they've first called the system. The list might look somewhat like the following: Your File Statistics: Your adjusted CPS (characters/second) transfer rate is: 256 Your upload areas: ACEFHIJKL Your download areas: ACEFHIJKLZ FREE download areas (not affecting UL/DL ratio): CFJ Your list areas: ACEFHIJKLZ Totals: You've uploaded about 30 Kbytes in 2 files You've downloaded about 102 Kbytes in 6 files MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-22 Using Magnum BBS as a USER The FILES MENU You've downloaded 2 files from FREE download areas Your totals for the week: You've downloaded about 0 Kbytes in 0 files Maximum allowed: 70000 Kbytes or 700 files Note that "Your totals for the week:" is displayed to those who have a period type of "Weekly". "week" would display as "day" to daily users, "month" to monthly users, and "year" to yearly users. FILEMENU_GOODBYE: (menu selection G) This menu selection is identical to the Goodbye selection in any other menu (main menu, message menu, etc). It firsts prompts the user for a confirmation of their intentions to log off, then prompts the user for whether they wish to leave a Comment to the sysop (see the VERIFY_GOODBYE option in the STARTUP file). FILEMENU_HELP: (menu selection ?) This menu selection will display the file FILEHELP.BBS in the HELP directory if it exists, otherwise it will display a "Help not available" message. FILEMENU_EXT: (menu selection A) This menu selection (EXT stands for EXTernal programs) allows the user to Access a compressed (ARC or ZIP) file. The user can view the list of members within a compressed file, read any readable members, or download any of the members within the file. This selection does not require a file extension (ie: .ARC, .ZIP, etc) - it will find the file matching the first acceptable extension. By 'acceptable extension', we mean .ARC and .ZIP (built in). You can add support for additional compressed file formats (which Magnum will recognize and process) by creating or updating the file COMPRESS.LST in your SESSION DIRectory. -> If you wish to provide Magnum with compression formats in addition to -> .ARC and .ZIP compression formats, refer to the description of -> COMPRESS.LST in the chapter entitled "Back to Display Files & -> Subdirectories", in the "SESSION Directory" section of that chapter. FILEMENU_READ: (menu selection R) This menu selection allows the user to read a non-binary file. A non-binary file is a file containing only readable text (ie: files with extensions of .EXE, .COM, .SYS, .DLL, .ZIP, .ARC, etc are binary files and not readable). If a file is read in this fashion, rest assured that any imbedded MILC commands (either intentional or non-intentional) are ignored (not processed). FILEMENU_CHANGE: (menu selection C) This menu selection allows the user to change a file they uploaded. First, Magnum will prompt the user for the filename: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-23 The FILES MENU Name of file to change? (blank quits) => If the user supplies a filename they didn't upload, Magnum will disallow any changes. Otherwise, a display similar to the following would show: File was found in area "E" Filename: "MAGCOM.ZIP" - Area: "E" - Public Expiration Date: None Detailed Description: Does not exist 1-line Description: MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem 0) Quit 1) Delete 2) Change Area (E) 3) Make Private (password protect) 4) Change FileName (MAGCOM.ZIP) 5) Change Expiration Date () 6) Change Brief (1-line) description 7) Add Detailed Description Choice (0-7) => The above submenu is self-explanatory. The user can change 7 different things for any file they've uploaded. FILEMENU_MAKELIST: (menu selection M) This menu selection is identical to the [N]ew Files selection, except that it's output is compressed into a .ZIP or .ARC file (depending on the user's Environment default for System Compression Type). The resultant .ZIP or .ARC file is password protected with the user's logon password, and placed in the RJE file area for download. It is automatically marked with an expiration date of the next day. If the user downloads the file successfully before midnight, the file is deleted immediately. This menu selection creates an up-to-date list of all files available for download on the BBS (which the user is authorized to download). Note that the created filename has the format Uxxxxx@y.ZIP (or .ARC) where xxxxx is the user's ID number (up to 5 digits), and y is a hex number ranging from 0 to F indicating how many of these RJE files s/he created today. If y is 0 this is the first file, if y is 5 this is the 6th file. If y is F this is the 16th file and Magnum will disallow creation of any more RJE files for this user until the next day. FILEMENU_OPT1: (menu selection 1) FILEMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file FILEOPT1.BBS or MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-24 Using Magnum BBS as a USER The FILES MENU FILEOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. FILEMENU_BASE: (menu selection F) This menu selection is for those who've purchased [and installed] our 'Extended MessageBase' module. If you're not using this module, you should raise the security level of this menu option such that it does not appear on any user's screen. FILEMENU_UTILS: (menu selection E) This menu selection is identical to choosing the [U]tils selection when at the "- More -" during file listings. This selection allows the user to mark files, unmark files, access compressed files, obtain detailed information on files, modify their list of marked files, etc. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-25 The SYSOP MENU The SYSOP MENU currently has 11 menu selections available: SYSMENU_QUIT: (menu selection Q) Like any other QUIT MENU command, selecting this menu option will return the user to the main menu. SYSMENU_CMD: (menu selection O) This menu selection will invoke the operating system's CMD.EXE (OS/2's command interpreter). This is available whether the user is on locally or remotely. To exit the command interpreter and return to the BBS, enter the command EXIT followed by your ENTER key. SYSMENU_PRINT: (menu selection P) This menu selection gives you the option of printing the user database (one page per user) or address lables. Choosing this menu selection results in Magnum prompting you for which filename or device to print to. In most systems, PRN is the device name of the printer. If you specified a filename instead, output will be printed to that filename. The next prompt you will see asks which security level you wish to print. The prompt after that asks if you want [R]ecord information or [A]ddress Labels to print. If you choose [A]ddress Labels, you'll get a "[P]rint, [A]lignment" response. By choosing [A]lignment, Magnum will print 2 dummy labels on your printer, giving you a chance to align the labels in your printer. Once you're satisfied with the alignment, choose not to reprint the test - Magnum will then print the address labels. Note that you can press <Ctrl-X> during printing to abort. If you're printing address labels, it's recommended to set your printer in condensed mode. Magnum assumes 6 lines between labels and assumes each label can hold 5 lines of address information (the 6th line is a blank line separating labels). NOTE: You may also print out "Mail" accounts. SYSMENU_MSG: (menu selection M) This menu selection allows the user (sysop) to fiddle with the message database. When you select this option, the record for the first message on the system is displayed along with the prompt for this area. The display might look similar to the following: MSGBASE: 0 RECNUM: 0 (actual), 0 (recorded) DELETED: N CONF: H PRIVATE: N RECEIVED: N, MSGMILC: '@', ECHO: N FROM: /0 (CHUCK B GILMORE) TO: ALL NUM: /0 #READ: 68 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-26 Using Magnum BBS as a USER The SYSOP MENU SUBJ: Welcome! DATE: 09/01/1989 TIME: 06:00 FROM_PSERNUM: 1234567890 EXPDATE: (nul) TO_PSERNUM: 1234567890 CC: N SENT: Y FWD: N USERNAME: "CHUCK B GILMORE" RECEIPT: N REPLIES: N ISREPLY: N RECVD_DATE: (nul) RECVD_TIME: (nul) FILENAME: H9010916.835 FIELDNAME, Next, Quit, Prev, Match, Ref, Erased, Hardcopy, Base, From, To, Userid, Date, Subj, View => The fields listed are all changeable except for the RECNUM field which is merely an informative field for your information only. To change any of the fields, enter the full fieldname. For example, to change the SUBJ field, type SUBJ followed by your ENTER key. You'll get a prompt asking for the new SUBJ which you might respond with "Welcome to Magnum BBS!". You can change any of the fields simply by entering the name of the field and pressing ENTER - Magnum will then prompt you for the new value of the field. All fields which hold one of two values (Y or N for Yes or No) are called boolean fields (boolean refers to fields which can hold one of two things - Yes or No, or programmers are more familiar with TRUE or FALSE). Except for the CONF: field which can hold any alphabetic value, boolean fields can be interpreted (via example) as: DELETED: N simply ask yourself a question with the fieldname - Is this message DELETED? The value shows N, therefore, NO, the message is NOT deleted. Let's try it with another boolean field: ISREPLY: N simply ask yourself Is this message a reply (to a previous message)? The value shows N, therefore, NO, the message is NOT a reply. Since the values for the fields are self-explanatory once you understand what the fieldnames refer to, let's describe what each fieldname refers to: MSGBASE: Will always be 0 unless you're using the optional 'Extended MessageBase' module, otherwise can be 0 to 255. RECNUM: Not Changeable - for your information only DELETED: Boolean field (Y=Deleted, N=Not Deleted) CONF: Conference area of message (one of A to Z) PRIVATE: Boolean field (Y=Private, N=Not Private) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-27 The SYSOP MENU RECEIVED: Boolean field (Y=Received by addressee, N=not received) MSGMILC: Shows the MILC command character used for this message. This does not necessarily mean that any MILC commands were used. ECHO: Shows whether this message is echoable (Y) or not (N) to other systems. Echoable messages generally have different 'from' and 'to' serial numbers. FROM: Who composed the message (ie: /0 (CHUCK B GILMORE)) TO: Who the message is to (ie: /IDNUM (Firstname M, Lastname) or ALL) NUM: IDNUM of original addresse (if this is a CC or FWD message) #READ: Number of times message was read. SUBJ: Subject of message. DATE: Date of message TIME: Time of messaage FROM_PSERNUM: The serial# of the originating BBS (usually yours). TO_PSERNUM: The serial# of the target BBS (usually yours). SENT: If the 'from' and 'to' serial numbers are identical, this field will always be Y (yes). However, if the 'from' and 'to' serial numbers are different, it will be Y (yes) only if the message has been sent via AMMO (refer to chapter on Magnum-to-Magnum Remote Mail), otherwise N (no). EXPDATE: Expiration date of msg (MM/DD/YYYY or DD.MM.YYYY) or (nul) CC: Boolean field (Y=this is a CC (carbon copy), N=this is not a CC) FWD: Boolean field (Y=this is a forwarded message, N=not forwarded) RECEIPT: Boolean field (Y=receipt requested, N=no receipt requested) REPLIES: Boolean field (Y=replies exist, N=replies do not exist) ISREPLY: Boolean field (Y=this is a reply, N=this is not a reply) RECVD_DATE: Date msg was received (MM/DD/YYYY or DD.MM.YYYY) or (nul) RECVD_TIME: Time message was received FILENAME: Filename of file holding actual text of message (same as REF# but with the . to delimit the filename extension). Note that the first character of the filename determines which subdirectory (A-Z) of the MESSAGE subdirectory MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-28 Using Magnum BBS as a USER The SYSOP MENU houses the file. This explains the FIELD entries. The actual prompt: FIELDNAME, Next, Quit, Prev, Match, Ref, Erased, Hardcopy, Base, From, To, Userid, Date, Subj, View => expects you to enter either a FIELDNAME, or one of the 6 command letters (N,Q,P,M,R,E,F,T,U,D,S,V). The command letters are defined as follows: N = Next. Show next message entry (wraps to 0 if at end of database). Q = Quit. Quits message database section and returns to Sysop menu. P = Prev. Show previous message entry (wraps to last entry if at beginning of database). M = Match. Prompts for a Conference letter to match. All Next and Prev commands will only display the records who's conference area matches what you've supplied here. R = Reference#. You can supply a reference# here and Magnum will bring up the record for that message. E = Erased. Magnum will only display records for those messages which have been erased (deleted). If you haven't done a "[S]tatus of Databases" command, then erased messages should still be Viewable (with the View command), otherwise the message really is deleted (refer to the DELETED field). H = Hardcopy. Prints message on your printer, unprocessed. B = Base. If using the optional 'Extended MsgBase', you can change the MsgBase here. F = Only display records who's FROM field matches the FROM ID you'll supply in answer to this prompt. T = Only display records who's TO field matches the TO ID you'll supply in answer to this prompt. U = Only displays recrods who's FROM or TO field matches the user ID you'll supply in answer to this prompt. D = Date. Only displays records which are greater than or equal to the date answer you'll supply in answer to this prompt. S = Subject. Only displays records which match the Subject field you'll supply. V = View the message text. This is identical to reading the message when in the "Read Messages Submenu". The difference is that when you choose the View option from here, Magnum will not update the message header (ie: won't count it as being read or received, and no receipt will be generated if the message is to you with a receipt requested). As you can see, the Message Database area of the Sysop menu can be a very powerful utility. You can change most any field of any message header. NOTE THAT ALL CHANGES MADE TO "FROM" AND "TO" MUST START WITH THE '/' CHARACTER (note that a recipient of ALL is designated as /-1). Note that if you choose 'H' (hardcopy), you will be prompted for a file or devicename to print the message out to. Printing will print any imbedded MILC commands unprocessed. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-29 The SYSOP MENU SYSMENU_USER: (menu selection U) The USER DATABASE area of the Sysop Menu is another powerful sysop tool. When you enter this area of the Sysop menu, the record for ID /0 (Sysop) will automatically be displayed. As with the Message database area, ANY fieldname (with the exception of the USER ID) is changeable. An example user record might look something like the following: LASTNAME=DOE, FIRSTNAME=JOHN, MIDDLENAME=C ID=/0, STREET1=John Doe's BBS, TYPE=U, REUSE=N STREET2=12345 Abbey Road CITY=Los Angeles, STATE=CA, ZIP=90067, COUNTRY=USA FIRSTCALL=10/05/1989, LASTCALL=01/12/1990, TIMELAST=18:24 PASSWORD=NHOJ, DOB=07/01/1958 (age: 31), DATEFORMAT=U, RJEJOBS=3 PHONE1=213-555-1234, PHONE2=213-555-4321 CPUTYPE=IBM PS/2 model 80, CONFERENCES=ACEFGH MEMODATE1=, MEMODATE2=, PRIVMSG=Y, DELMSG=Y, SUB_FILEDEL=N SYSOP_COMMENT=Master SYSOP XFERTYPE=N, PERIODTYPE=W, EXPERT=N, LOCKED_OUT=N, COLOR=Y, DISPLAY_MO ERASE_MORE=Y, HOTKEYS=Y, LINES_PAGE=23, LEVEL=1000, UPLOADS=102 DOWNLOADS=36, CPS=2056, UDRATIO=0, TTL_CALLS=413, REMAINING=94 REMAINING_PERIOD=659, K_UL=4568, K_DL=2171, PERIOD_DL=700 PERIOD_K_DL=70000, DL_THIS_PERIOD=0, K_DL_THIS_PERIOD=0 DAILY_TIME=120, DAILY_DL=100, DAILY_K_DL=10000, PRIVACY=OFF FILE_U_AREAS=ACEFHIJKLSZQ, FREE_DL_AREAS=CFJ FILE_D_AREAS=ACEFHIJKLSZQ, FREE_DOWNLOADS=1 FILE_L_AREAS=ACEFHIJKLSZQ, FILEGRP=0, FILEBASE=0 MSG_R_AREAS=ACHKLSWZ, MSGGRP=0, MSGBASE=0, RMAIL=N MSG_W_AREAS=ACHKLSWZ MSG_L_AREAS=ACHKLSWZ DISP_CMDS=ABCDEFGHIJKLMNOPQRSTUVWXYZ, COMPRESS=Z, PRIVM=108, PUBLM=34 I= OS/2 PM COMMUNICATIONS BBS COMMAND (FIELDNAME, Quit, Match, Nxt, Prev, Srch, Del, /ID) => The last line of the display (in hi-intensity cyan on color systems) prompts you for either a FIELDNAME or the first letter of one of the 6 commands (Quit, Match, Nxt, Prev, Srch, Del), or the ID number (beginning with the forward slash (/) character) of the user who's record you'd like to bring up. If you are seeing the display in color, FIELDNAMES appear in hi-intensity green, while their changeable values appear in hi-intensity white. Note that any field (with the exception of ID) can be changed. The ID number is identical to the record number (position in database file), which is why the user database is not packable (unlike the file and message databases which are packable). We've already explained what supplying a forward slash and user ID does, so lets explain the other 6 commands. Only the first letter of the other 6 commands need be supplied (ENTER key is required after making any selection here). The Quit command quits the User Database area and returns you back to the Sysop Menu. The Match command prompts you for a security level (or match on MAIL accounts) - after you answer that prompt with a security level, Magnum will display only those users in the database who's security level matches the one you just supplied - MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-30 Using Magnum BBS as a USER The SYSOP MENU this will be true for the Nxt and Prev commands as well - use the Quit command to stop the Match process. The Nxt command will bring up the next record in the user database - if you're already at the highest record number, it will wrap to record 0. The Prev command will bring up the previous record number - if you're currently at record number 0 (ID of /0), it will wrap to the last record (highest record number) in the database. The Srch command will invoke the User Search command which is identical to the MAINMENU_USERS (main menu selection U) command. The Del command will prompt you as to whether you wish to delete this user - if you delete the user, you can undelete them later by issuing the /ID command and answering Yes to the "undelete" prompt (unless the user id has been re-assigned to a new user). The FIELDNAME's are all self explanatory. Simply enter the FIELDNAME of a field you wish to change. A prompt for the new fieldname will appear asking you for the new value to assign to the field. Note that if you wish to change the MIDDLENAME field of a user's record to blank (none), you'll need to change the MIDDLENAME to a value of X (the letter X). Note that if you are changing a user's record and that user happens to be online at the same time, all fields will accept and apply the change except for the LEVEL field. To change the security level for a user who's already online, you'll need to change it at the MBBS sysop console with the "x LEVEL yyyy" command (where x is the node they're on, and yyyy is the new security level). Note that MEMODATE1, MEMODATE2 and SYSOP_COMMENT are for your (Sysop) private use - you may do with these fields as you wish. The memodate field is typically used when you're running your BBS as a subscription BBS system. You would enter the user's subscription expiration date in this field and use MBBSEXEC.EXE (see the chapter on MBBSEXEC) sysop utility to lower this user's security and access levels on the user's expiration date. The only other field that needs some explaining is the DISP_CMDS field. Refer to the chapter on MILC commands. This field contains the letters (A-Z) of allowable MILC commands the user can use in message text. Typically this value is "AO" (@A commands are for color, @O commands are for other, miscellaneous information display). In this case, the Sysop's record is being displayed, and the Sysop should be able to issue ANY MILC command within any message text s/he likes - therefore, all letters of the alphabet are defined (even though there aren't that many MILC categories - this way, you won't have to change it for future releases of Magnum which may contain additional categories of MILC commands in the future). If a user enters a MILC command in a message text which isn't allowed (not in the DISP_CMDS of the user's profile), Magnum will simply display the MILC command when someone reads the message as though it were normal text but it won't process it. Other fields which may need additional explanation: The REUSE and TYPE fields appear near the top of the screen (after STREET1) and the FILEGRP and MSGGRP appear near the bottom (after FILE_L_AREAS and MSG_R_AREAS). Note that FILEGRP, MSGGRP, FILEBASE and MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-31 The SYSOP MENU MSGBASE apply to those sysops using the extended FileBase and/or Extended MsgBase modules. Note that TYPE applies to those sysops using the Magnum Remote Mail option. TYPE can be one of U (user) or M (mail). REUSE can be one of Y (yes) or N (no) - If N (no), this record is NOT reusable in the event you delete this user. The RMAIL field indicates whether the user can enter a message to a user on a remote Magnum system. The default is NOT to have this capability, however you may change this default for any/all users either individually in the User Database area of the Sysop Menu, or in bulk with a .MEX program. For those running the extended file or msgbase modules, refer to the chpater on Extended Filebase and Extended MsgBase modules. SYSMENU_FILE: (menu selection F) This menu selection will enter the Files database. First, you'll see the following prompt: B)ase, F)ile Utils, A)dd Files (B,F,A) (blank quits) => By simply pressing ENTER (without entering a response), you'll quit this section and go back to the Sysop Menu. By choosing B, you'll be allowed to change the FileBase (applicable only if using the optional 'Extended FileBase' module). By Choosing F, the following prompt will appear: Search by A)rea or F)ilename (A,F, blank quits) => By choosing A, you'll be prompted for a file area (A-Z) in which to add a file from. The file must already exist in that file area! By choosing F, the following prompt will display: Search by A)rea, F)ilename or U)ser (A,F,U - blank quits) => If you choose A)rea, then the records matching that file area will display in sequential order, starting with the first one it finds. You'll be given a chance to modify any of the fields in any of the records while it's being displayed, or you can go on to the next record matching the file area, or quit. If you choose F)ilename, the record of the filename will appear. If you choose U)ser, then all files uploaded by that user (filenames only), will be displayed. When a file record is displayed, it might look like the following: FileName: "MAGCOM.ZIP" - Area: "E" - Public Expiration Date: None Detailed Description: Does not exist 1-line Description: MAGCOM communications pgm for OS/2 from Gilmore Systems. X,Y,Zmodem MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-32 Using Magnum BBS as a USER The SYSOP MENU 0) Quit 1) Delete 2) Change Area (E) 3) Make Private (password protect) 4) Change FileName (MAGCOM.ZIP) [#204] 5) Change Expiration Date () 6) Change Brief (1-line) description 7) Add Detailed Description 8) Upload method (G) 9) File Date (01/01/1990) 10) File Time (06:41) 11) Last Accessed (01/08/1990) 12) ID# of uploader (/0) 13) Delete detailed description (NonApplicable) 14) Size of file (80896) 15) Number of downloads (67) 16) FileBase (000) 17) View ZIP Choice (0-17) => Note that choices 0-7 are identical to the FILEMENU_CHANGE (file menu option C) except that choices 8-17 have been added for the rest of the record to be available for changes by the sysop. All parameters here are self explanatory. When you quit (0) this selection, you will return to the previous prompt - if you're searching by area, you'll be prompted as to whether you wish to see the record of the next file in the area or if you'd like to quit. The other selection of the Files Database section of the sysop menu is the A)dd files selection. Choosing this option first requires that the file you are about to add has been placed in the directory matching the file area you wish to add the file to. In other words, if file area F is defined as "E:\MAGNUM\NEWFILES", then the file you are about to add to the database should already be placed in this directory. By choosing the A)dd files selection, you will be prompted for the name of the file you are about to add, followed by a prompt for the area the file is to be found in, and a description of the file. SYSMENU_ACTIVITY: (menu selection A) This menu selection is actually two different functions in one. The main purpose for this function is to view the activity logs for the individual nodes. The prompt appearing when you select this option is as follows (we're assuming 4-node version): Activity for which node (1-4) => By supplying a node number, the log for that node will be displayed (BACKWARDS) in reverse chronological order. If you anser the prompt with a question mark (?) followed by a node number, for example: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-33 The SYSOP MENU Activity for which node (1-4) => ?1 you will be placed in "Remote Snoop" mode. In other words, you will be able to see everything the user on that node sees. This is intended for sysops who are logged on remotely and wish to "snoop" on someone as though they were sitting at the master console and typed "1 switch". To end "remote snoop", simply press <Ctrl-X>. Important notes about "remote snoop": Characters are placed in a circular buffer of 512 bytes. If you are logged on at a lower baud rate than the user you are "snooping" on, you may experience loss of characters in this mode. Also, if the user is performing a file transfer (upload or download), the usual display of "Bytes Sent" or "Bytes Received" will not be visible! Do not be alarmed at this. Do not try to use this "remote snoop" facility while logged on locally - a decrease in priority is issued to the local node and you will lose MANY characters of snoop display. SYSMENU_REMOTE: (menu selection R) This menu selection will work only for sysops who've logged on remotely (will not work if logged on locally via the console). This area of the BBS emulates the MBBS Sysop console. You can issue ANY MBBS command that you'd ordinarily have to be sitting at the Sysop console to issue. You can make any node(s) active, inactive, schedule a node for shutdown, force a user off, etc. The only thing you can't do is issue the "* logon" command (it will be rejected). When you first enter this menu selection, Magnum will send the "MAGNUM SYSOP CONSOLE Display Screen" to your remote terminal, and prompt you for a MBBS command. After any command you enter, it will be processed and the "MAGNUM SYSOP CONSOLE Display Screen" will be redisplayed on your remote terminal. To end this "remote sysop console" mode, simply ENTER a null command (just press ENTER without typing anything at the command prompt). NOTE: "TEST mode" is not possible via this option - it is available only at the sysop's console (keyboard) on the machine running Magnum. SYSMENU_STATS: (menu selection S) This menu selection displays the status of the databases. NOTE: BY CHOOSING THIS MENU SELECTION, ALL EXPIRED FILES AND MESSAGES WILL BE PHYSICALLY DELETED, NOT JUST MARKED FOR DELETION! ANY FILES OR MESSAGES MARKED FOR DELETION WILL BE PHYSICALLY DELETED! By choosing this menu selection, you'll see a display similar to the following: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-34 Using Magnum BBS as a USER The SYSOP MENU MAGNUM OS/2 BBS - (C)Copyright 1989,1992 Gilmore Systems # Records = Active + Deleted USER DATABASE: 000647 000647 000000 (unpackable) FILE DATABASE: 000432 000414 000018 MSG DATABASE: 001407 001391 000016 [F]=Pack File Database, [M]=Pack Message Database, [Q]uit Choice (F,M,Q) => Even though physical deletions are performed, an entry in the databases (File and Message databases) still exist for the deleted records. You must perform a Pack of the databases to recreate the databases - this will eliminate the deleted records and free up some space. IMPORTANT: WHEN PACKING DATABASES, MAGNUM WILL CAUSE ALL SESSIONS (OTHER THAN YOURS) TO TERMINATE. ALL NODES (EXCEPT YOURS) WILL ALSO BECOME INACTIVE. THIS APPLIES TO *ALL* SESSIONS AND NODES REGARDLESS OF WHERE THEY'RE LOCATED ON YOUR LAN. MAGNUM WILL GIVE YOU THE COURTESY OF PROMPTING YOU AS TO WHETHER YOU WISH TO CONTINUE WITH THE 'PACKING' BEFORE IT DOES ANYTHING - THIS WILL ALLOW YOU TO CHANGE YOUR MIND. THERE MUST BE ENOUGH FREE DISK SPACE TO HOLD AN EXTRA COPY OF THE DATABASE(s) YOU ARE PACKING! IT IS A GOOD IDEA TO MAKE A BACKUP COPY OF THE DATABASES PRIOR TO PACKING THEM. While packing message or file databases, the system displays + and - characters on the screen. A '+' character displays for every processed record, a '-' character for every record it deletes. At pack completion status is redisplayed, and the number of records in the database should should match the number of active records (deleted records should be 0). It's necessary to pack the databases periodically. Depending on how active your BBS is, we found that once per week suits most busy boards. NOTE: From time to time the number of records reported in the USER database will not match the number of actual records in the user database as reported by the "[V]iew System Statistics" from the main menu. This is normal, and eventually the two will match. The number of records in this option is derived from the number of records in the USER.KEY file rather than in the USER.DAT file. The USER.KEY file will ocassionally contain more records than the USER.DAT file due to aborted NEW USER logons. SYSMENU_HELP: (menu selection ?) This menu selection displays the help file SYSHELP.BBS (in the HELP directory) if it exists, otherwise a "Help not available" message is displayed. As of this writing, a help file is not included for the MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-35 The SYSOP MENU Sysop menu, but you can feel free to write your own should you be inclined to do so. SYSMENU_GOODBYE: (menu selection G) This menu selection is identical to the GOODBYE function on any other menu. It prompts the user as to whether they're sure they want to disconnect, and whether they'd like to leave a comment to the Sysop prior to disconnecting (see the VERIFY_GOODBYE option in the STARTUP file). SYSMENU_OPT1: (menu selection 1) SYSMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file SYSOPT1.BBS or SYSOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 7-36 Using Magnum BBS as a USER The RJE MENU The RJE MENU currently has 8 menu selections available: RJEMENU_QUIT: (menu selection Q) Like any other QUIT MENU command, selecting this menu option will return the user to the main menu. RJEMENU_STATUS: (menu selection S) Choosing this menu selection will display the status of any RJE job(s) you started. First, you'll be prompted for a date which Magnum will use to start the search from. After you've responded to this prompt, the display might look similar to the following: (Seconds) (S e c o n d s) RJE_NAME START_DATE START STOP_DATE STOP TTL_TIME STATUS C L PID 50F0A12935 05/15/1990 12935 05/15/1990 12988 63 done 1 25 918 50F0A18043 05/15/1990 18043 running 1 25 926 The above example display shows the RJE_NAME (job name Magnum assigned), the date started, the time started (in seconds from midnight). If the job is still running, the STOP_DATE and STOP time will be meaningless, otherwise they'll be filled in. The STATUS tells whether the job is still running or whether its complete. C stands for priority CLASS, and L stands for priority LEVEL within the priority class. PID will only appear if the Sysop is listing the status of jobs, and will not appear for normal users. PID is the Process IDentification of the job. See the explanation of the @E command for further information. RJEMENU_LIST: (menu selection L) When a user selects this option, Magnum will display the RJELIST.BBS file (from your RJE DIRectory) if it exists. See our sample RJELIST.BBS file (in your RJE DIRectory for an example of how to put this file together). Upon exit of displaying this file, Magnum will run the program contained in MILC variable @Z0 with the parms in @Z1. It's suggested that you use the @E1 command to run RJE programs instead, and blank out the @Z0 variable prior to exiting this file (ie: @Z0=""); RJEMENU_DELETE: (menu selection K) Choosing this option will result in Magnum prompting you for the 10-character jobname of the RJE job you wish to kill (terminate). If the job is still active (running), Magnum will terminate it. RJEMENU_FILES: (menu selection C) This menu selection will list the completed RJE jobs ready for you to download, giving filename, creation date, expiration date, and size. RJEMENU_SYSOP: (menu selection X) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Using Magnum BBS as a USER Page 7-37 The RJE MENU This menu selection will allow the Sysop to perform the L and C options above but will be able to supply a user id instead of his/her own. The L option equivalent will also show extended information about the job, such as the program name, and the parameters which were used to pass to the program. RJEMENU_HELP: (menu selection ?) This menu selection will display the RJEHELP.BBS file from the HELP DIRectory. RJEMENU_GOODBYE: (menu selection G) This menu selection prompts the user as to whether they really want to end their session or not. If Yes, they are prompted as to whether they wish to leave a Comment to the Sysop prior to disconnecting (See the VERIFY_GOODBYE option in the STARTUP file). RJEMENU_OPT1: (menu selection 1) RJEMENU_OPT2: (menu selection 2) These menu selections are normally turned off by setting the security level to that of one higher than any of your users unless you plan on using them. When selected, Magnum will display the file RJEOPT1.BBS or RJEOPT2.BBS from your DISPLAY DIRectory if it exists. These files are created by you in order to supply 'hooks' to external programs in areas other than Child (door) or RJE menus by embedding MILC commands into these files. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - This concludes chapter 7 "Using Magnum BBS as a User". After using the BBS as a Sysop for a while, you'll see why we chose to write the system as a text application rather than as a PM application. Because it's a text application, you can log on to your BBS remotely as Sysop from any terminal regardless of operating system and perform any sysop function you'd ordinarily have to be at the Sysop console to do. You'll find Magnum BBS to be a powerful, full-featured BBS when compared to other BBS systems. The remaining chapters in this manual deal with advanced Sysop functions. It is suggested that you become familiar and comfortable with everything covered so far before attempting to deal with the following chapters. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank Magnum's ACE (Automatic Command Execution) Event Handler Page 8-1 Incorporated into Magnum BBS, is a powerful event handler known as ACE. ACE is an acronym for "Automatic Command Execution" because that's exactly what it does - automatically executes commands at predetermined days and times. When you first start Magnum BBS by starting the MBBS.EXE program, part of the MBBS.EXE startup routines look for a file by the name of MBBS.ACE in the PROGRAM directory (the same directory that MBBS.EXE is found in). This is why it's important that you make the current directory your PROGRAM directory prior to starting MBBS.EXE. If MBBS.EXE finds the file MBBS.ACE, it reads the file and stores or queues any ACE commands it finds within the file and issues a message similar "xx ACE commands queued". ACE commands are of two types: stored (queued), and immediate. Stored or queued commands are executed on predetermined day(s) and times. Immediate commands are those which are executed right away. When MBBS.EXE starts up, it will attempt to read the file MBBS.ACE (if it exists), and store the appropriate ACE commands within for later execution. MBBS.ACE is expected to be found in the PROGRAM directory - the same directory MBBS.EXE is in. MBBS.ACE is a normal text file which you create with your text editor. Blank lines are ignored, and lines starting with the exclamation mark character (!) will be treated as comments (ignored). Since blank lines and lines starting with the ! character are ignored by MBBS, now would be a good time to introduce you to an actual MBBS.ACE file. From this point on, the rest of the documentation for ACE will be in the format expected to be found in the MBBS.ACE file (beginning with the - - - CUT - - - line, and ending with the - - - CUT - - - line. Most of the following are comments): ! - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT ! To use MBBS automated commands, you need to create an MBBS command ! file. To accomplish this, you'll need a text editor to create the file ! ! The file should have a name of MBBS.ACE (where ACE is an ! acronym for Automatic Command Execution). The MBBS.ACE file should be ! placed in your PROGRAM directory (the same directory as MBBS.EXE ! resides in). ! Here is the Syntax of an MBBS ACE command: ! CCCCCCC,HH:MM,SSSSSSSSSSSS[,wwww] ! ^ ^ ^ ! | | | ! | | | ! | | |_Command (see below) ! | | ! | |_Time (hh:mm) in 24-hour format (range is 00:00 to 23:59) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 8-2 Magnum's ACE (Automatic Command Execution) Event Handler ! | ! |_Days applicable (0=Sun,1=Mon,...6=Sat) ie: 12345 applies to Mon-Fri ! Text lines starting with the '!' character are comments (ignored) ! MBBS has a physical limit of 100 command lines. This means that the ! MBBS.ACE file must not contain more than 100 commands. Blank lines and ! comments (lines starting with the ! character) are not commands and ! are not counted in the 100 command limit. "Immediate Commands" ! (commands starting with the * character described later) are not ! counted in the 100 command limit either. ! Description of Command: ! The Command SSSSSSSSSSSS can be any Magnum MBBS command just as you'd ! enter on the MBBS command line beginning with the node# or *, OR it ! can be any enclosed in double quotes (" ") if it's a command you wish ! to have OS/2 run instead. If you're using OS/2 commands (in double ! quotes), an additional parameter must follow - WAIT, NOWAIT or DETACH. ! Please realize the consequences of the WAIT parameter: MBBS comes to ! a grinding HALT (won't answer phone, won't accept commands, etc) until ! the process it's WAITing for finishes. With the NOWAIT or DETACH ! parm, the process runs in the background while MBBS continues to run. ! If the process you're starting (in double quotes) writes to ! stdout/stderr (the screen/console), you should redirect it's output to ! the nul device, or to files (redirection is accomplished with the < ! character and the > characters. Example MBBS commands will follow ! later. ! NOTE: MBBS.EXE can read (and store) a maximum of 100 ACE commands. ! With the Alternate Syntax described below (immediate execution ! rather than stored for later execution), immediate ACE commands ! are NOT counted as part of the 100 maximum limit because they ! are executed immediately (as soon as they're read) and then ! discarded (not stored). Also note that the MBBS command (entered ! manually at the "Command ==> " prompt) of "* ACE INIT" will ! re-read the MBBS.ACE command file, overwriting all previously ! stored ACE commands with the ACE commands just read with one ! exception - Immediate commands (those starting with the * char) ! will be ignored - immediate commands will ONLY be processed when ! the MBBS program is initially started. This insures that dual ! copies of the same program(s) are not running unintentionally. ! Also, another MBBS command (entered manually at the ! "Command ==> " prompt) of "* SSSSSSS,wwww" has the same syntax ! as the ACE "immediate" command except that no comma follows ! the * char. ! ! ! Alternate Syntax: ! ! *,SSSSSSSSSS[,wwww] ! ! When used this way, the command executes immediately. When MBBS.EXE MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum's ACE (Automatic Command Execution) Event Handler Page 8-3 ! starts, it reads the commands in the MBBS.ACE file, when a command ! starts with the * character, it is executed immediately! ! ! Internal MBBS commands may be entered exactly as you'd enter them at ! the MBBS command prompt (Command ==> ). External commands - ! programs, .CMD files, or any other command you'd type at the OS/2 ! command line are to be enclosed within double quotes immediately ! followed by a comma (,) and one of the keywords: WAIT, NOWAIT or ! DETACH, where these keywords are defined as: ! ! WAIT - MBBS stops what it's doing and starts the external command ! or program. MBBS will NOT resume until the external ! command finishes. Programs started in this fashion may ! use the console for input/output operations (stdin, ! stdout, stderr). ! ! NOWAIT - MBBS starts the external command or program and ! immediately resumes normal BBS operation while the ! external command or program executes concurrently. NOTE: ! Programs started in this fashion must NOT perform any ! console input/output operations. You may still run ! programs that use console input/output operations by ! redirecting their output to the NUL device, and ! redirecting their input to a file. For example, the ! command: "mbbsexec.exe 1>nul 2>nul" redirects all program ! output to the NUL device (a dummy file). For those of you ! unfamiliar with the redirection of output in this fashion, ! OS/2 predifines the first three file handles of any ! program as 0 (stdin), 1 (stdout), and 2 (stderr). By ! rerouting output with the statements "1>nul" and "2>nul", ! you ensure that both stdout and stderr are rerouted to ! the NUL device. Unlike DOS where ">nul" redirected both ! stdout and stderr to the NUL device, the same ">nul" ! statement in OS/2 only redirects stdout to the NUL device. ! It is important that NO output be written to the screen ! when a program is started with the NOWAIT option, and that ! no input is expected from the keyboard. ! ! DETACH - Similar to the NOWAIT option above, but with the following ! exceptions: The program will be started as a detached ! process which runs in the background, and concurrently ! with other processes in the system. Since the program is ! running as a detached process, it will continue to run ! until it finishes, even if MBBS.EXE is terminated for any ! reason. Console I/O operations are permitted ONLY via ! POPUP windows. ! !-------------------------- ! ! On Startup run program abc.exe and xyz.exe, make Node2 "announce only" ! !-------------------------- MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 8-4 Magnum's ACE (Automatic Command Execution) Event Handler *,"abc.exe 1>nul 2>nul",wait *,"xyz.exe 1>nul 2>nul",detach *,2 announce !-------------------------- ! ! On Mon thru Fri, Shutdown Node3 at 09:00 and - Activate again at 17:00 ! !-------------------------- 12345,08:00,3 shutdown 09:00 12345,17:00,3 Active !-------------------------- ! ! Prepare for System Maintenance at 02:00 every morning ! ! Note that node 4 (console) is left active, otherwise, if all nodes ! were shutdown, MBBS would terminate. ! ! Note that 02:01 is supplied for the time to run mbbsexec.exe, and for ! the commands following it to reactivate nodes 1-3. Even if ! mbbsexec.exe takes 20 minutes to complete, all commands scheduled for ! 02:01 will be processed in order. Since the WAIT parameter is ! specified, the reactivation of nodes 1-3 will not take place until ! mbbsexec.exe finsihes. It is also important to know that had the ! reactivation commands been scheduled for 02:02 (or 02:05) for example, ! and mbbsexec.exe took 10 minutes to complete, the time would be 02:10 ! upon completion and any commands scheduled from 02:01 to 02:09 ! inclusive would not be processed. Therefore, whenever you execute a ! program with the WAIT parameter, you should know how long the program ! will take to complete for obvious reasons. However, by supplying the ! reactivation commands (ie: 0123456,02:01,1 active) as in the sample ! below with the same time (02:01) as the program, you insure that the ! commands will be processed upon completion of the mbbsexec.exe ! program. The exception to this is any command(s) following the ! "shutdown" ace command. Note below how commands following "shutdown" ! are issued AFTER the scheduled shutdown time. ! !-------------------------- 0123456,01:00,1 shutdown 02:00 0123456,01:00,2 shutdown 02:00 0123456,01:00,3 shutdown 02:00 0123456,02:01,"mbbsexec.exe maintain",WAIT 0123456,02:01,1 active 0123456,02:01,2 active 0123456,02:01,3 active !--------------------------------------------------------------------- ! - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT - - - CUT MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum's ACE (Automatic Command Execution) Event Handler Page 8-5 This has been an explanation of the creation, syntax and usage of an MBBS.ACE command file. When you run the MBBS.EXE program, the MBBS.ACE file will be read and checked for syntax errors. ACE commands will be stored (queued) for later execution. Immediate commands will be processed right away. All executed ACE commands are logged to file ACE.LOG (in your PROGRAM directory) at the time of execution. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank The MBBSEXEC Sysop Maintenance Utility Program Page 9-1 MBBSEXEC Utility for "Magnum OS/2 BBS" (C)Copyright 1989,1992 Gilmore Systems - All rights reserved This chapter explains the use of MBBSEXEC.EXE, a Sysop utility program for the management of the Magnum BBS database files USER.DAT, USER.KEY, FILE.DAT, MSG.DAT, RJE.DAT, and UTILIZ.DAT. As a Sysop of a Magnum OS/2 BBS, you have probably discovered a great deal of routine things which you'd like to do with the contents of the records and fields within Magnum's databases. Some examples of these routine tasks which immediately come to mind are: - Delete all users whose last call was 180 days ago or greater - Delete all messages older than 90 days - Delete all files older than 365 days - Upgrade all users who've entered 2 or more public messages - Lower the security level of all users who's memodate has expired - Add an expiration date to all messages or files in a specific area - Increase time limit for users who've uploaded 10 or more files - Delete all files having less than 10 downloads in the past 60 days - List all users with an interest in music (or whatever you choose) - Upgrade Users ONLINE based on the results of a questionairre. - Generate Form Letters and/or Mailing Labels to all users matching specific criteria. - Generate reports showing what percentage of your users fall into specific criteria. This is just a very small example of what can be done with the MBBSEXEC program. There is virtually no limit on what you can do - MBBSEXEC simplifies all of your database management needs. MBBSEXEC is an interpreter (like BASIC) which interprets your programs (.MEX files) and performs the programming instructions within. This powerful interpreter is similar to the C programming language but has slightly stricter rules as far as opening and closing braces ( '{' and '}' characters). MBBSEXEC will be covered in two sections of this chapter. In the first section we'll start with a presentation of MBBSEXEC as a 'simple' programming language. This will provide those with little to no programming experience the information they need in order to write their own .MEX programs. By using MBBSEXEC as a 'simple' programming language, all of your Magnum database management needs can be taken care of. In the second section (the 'Advanced' section), we'll present advanced techniques oriented more towards those with programming experience, yet keeping it simple enough to understand (where possible) such that those new to programming can apply the advanced features to their .MEX programs. An MBBSEXEC program consists of a regular ASCII text file which you create with your favorite text editor. When you create an MBBSEXEC program with your text editor, you'll need to save it with a filename extension of ".MEX" (MbbsEXecutable). MBBSEXEC reads your .MEX file and processes the statements within. In other words, if you've created a MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-2 The MBBSEXEC Sysop Maintenance Utility Program text file to list all users with an interest in music, your MBBSEXEC input file would probably have a name of MUSIC.MEX, and you'd start MBBSEXEC with: MBBSEXEC MUSIC MBBSEXEC assumes an extension of .MEX although if you supply your own extension MBBSEXEC will use that filename instead. Following is an example of an MBBSEXEC program which will compile a list of all users who've listed MUSIC as one of their interests: ! ! List all users with an interest in MUSIC ! #CONFIG_FILE: E:\GS\MAGNUM\MBBSINIT.1 #LOG_FILE: MUSIC.LOG #DATABASE: USER #START if(@i ~ "music") { log("Interests: ",@i) log("ID: /",@id) log("lastname: ",@lastname) log("firstname: ",@firstname) log("middlename: ",@middlename) log("---------------------------") } #STOP Note in the above MBBSEXEC program, the very first thing you see is the exclamation mark (!) character. Any lines starting with the '!' character will be ignored - it merely serves as a comment line. The exclamation mark (!) always indicates the start of a comment - the comment always ends at the physical end of the text line the ! appeared in. There are only three exceptions as to when the ! character does NOT start a comment: - If it appears within double quotes ("...!..."). - If it is immediately followed by the "=" character ( != ). - If it is immediately preceeded & followed by single quotes ( '!' ). Next, three (3) '#' statements follow. The first is "#CONFIG_FILE:" which tells MBBSEXEC which database to work on by giving it the full filespec (path & filename) of the mbbs initialization file for Node01 (note the filename extension tells MBBSEXEC which node to work on). MBBSEXEC obtains all of it's information such as database names from this file. Usually MBBSINIT.1 is all that's needed since most BBS sysops running mulitple nodes are pointing the database files to the same SESION DIRectory. In the event that the Sysop is running 2 or 3 unique BBSes (different SESSION DIRectories and thus different user, MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-3 file, rje and message databases), you would need to change the #CONFIG_FILE statement to point to MBBSINIT.2 or MBBSINIT.3 so that those databases will also be changed. The second statement is the "#LOG_FILE: " statement which gives MBBSEXEC the filename (or device name such as "prn") in which to write statements to. The 3rd one is the "#DATABASE: " statement which tells MBBSEXEC which database to work on (can be USER, MSG, FILE, RJE or UTILIZ) - in this case, it's USER. Next comes the actual MBBSEXEC program which starts with the "#START" statement and ends with the "#STOP" statement - all text falling within the "#START" and "#STOP" statements are code or instructional statements. Examining the above code, we notice that the first code statement is: if(@i ~ "music") { Breaking down this statement, we note that the syntax of an IF statement is: if(expression) { where "expression" is some sort of comparison operation. In this case, the '~' character separating the "@i" from "music" is an operation which checks to see if string2 is contained within string1. In this case, string1 is "@i" which is MBBSEXEC's notation for "USER INTERESTS". Should the string "music" appear within string1 (USER INTERESTS), the result will be TRUE, otherwise FALSE. NOTE THAT THE OPENING BRACE ( { ) MUST APPEAR ON THE SAME LINE AS THE "IF(expression)" statement. In other words: if(expression) this is INCORRECT { . . } if(expression) { this is correct . . } If the "expression" is TRUE, then MBBSEXEC will perform the statements enclosed between the starting and ending braces ( { and } ). If the "expression" is FALSE, then MBBSEXEC will skip to the first statement following the ending brace ( } ). Please note that the ending brace must be on a line by itself, while the beginning brace must be the first nonspace character appearing after an "if(expression)" statement. Note that within the comparison expression, case (upper/lowercase) is not important. "music", "Music", "MUSIC", "MuSic" are all identical as far as MBBSEXEC is concerned. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-4 The MBBSEXEC Sysop Maintenance Utility Program Within the braces in the above example is a series of "log" statements. A "log" statement merely writes output to the "LOG" file you specificed in the "#LOG_FILE: " statement. The basic syntax of a log statement is: log("quoted string",@field) or log("quoted string") The "quoted string" parameter gets written to the log file, and the @field writes the current value of @field to the log file. In the former, @field can be any of the predefined user fields (we'll present a list of predefined field names later). MBBSEXEC will perform the statements between the #START and #STOP statements once for EACH record within the USER database. It will scan every @I field (user interests) for the word "MUSIC", and if the comparison is TRUE, MBBSEXEC will perform all of the statements within the { and } block. The list might look something like this: Interests: FISHING SWIMMING MUSIC CHESS ID: /158 lastname: SMITH firstname: JOHN middlename: S --------------------------- Interests: COMPUTERS MUSIC MIDI ID: /202 lastname: JOHNSON firstname: ALFRED middelname: E --------------------------- Interests: OS/2 MUSIC CARS BOATS ID: /303 lastname: DUNN firstname: JULIE middlename: SARAH --------------------------- This example only made a list of users with a specific interest. MBBSEXEC is also capable of modifying user fields as we'll see in a moment. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-5 MBBSEXEC Field Names MBBSEXEC incorporates predefined field names for accessing the individual fields within the databases. When you access the Sysop menu from within Magnum BBS, you'll notice that most of the field names for the User Database area will usually be the same names as those used by the MBBSEXEC program. The '@' character precedes all field names within the MBBSEXEC program. MBBSEXEC supports the USER.DAT and USER.KEY databases, the FILE.DAT database, the MSG.DAT database, the RJE.DAT and the UTILIZ.DAT database. NOTE: IT IS STRONGLY RECOMMENDED THAT YOU BACK UP YOUR *.DAT AND *.KEY FILES BEFORE RUNNING THE MBBSEXEC PROGRAM. THIS WAY YOU'LL BE ABLE TO RESTORE THE DATABASES IN THE EVENT OF AN UNEXPECTED ALTERATION TO THE DATABASES. IMPORTANT: IF AN ERROR OCCURS DURING PROCESSING YOUR .MEX FILE (SYNTAX OR OTHERWISE), AND A LINE NUMBER INDICATING WHICH LINE THE ERROR OCCURED, MBBSEXEC CREATES A FILE WITH AN EXTENSION OF .SNP (SNAPSHOT) - THIS .SNP FILE IS THE FILE IT IS REFERRING TO - NOT YOUR ORIGINAL .MEX FILE!!! IF YOUR .MEX FILE IS CALLED MUSIC.MEX, THE REFERENCE TO THE ERROR IS IN THE LINE NUMBER SPECIFIED BY THE ERROR MESSAGE IN FILE MUSIC.SNP Before beginning, we'll present the allowable field names for the 5 databases which MBBSEXEC will accept. Before presenting the list, we must point out that there is one fieldname used internally by MBBSEXEC which is not a part of the database fields. This fieldname is @TODAY which, when encountered in an MBBSEXEC program statement, is replaced with the current date. This allows such statements as: if(@lastcall < @today - 90) { @deleted = TRUE log("Deleted ID: /",@id) } The above statement would delete all users who's last call to the bbs was greater than 90 days ago from today. All MBBSEXEC fieldnames are case insensitive meaning that you can type these fieldnames in uppercase, lowercase or any combination. NOTE: All DATE fields are in U.S. format (MM/DD/YYYY) and must be 10 characters in length. Even if you're using a European version of Magnum, the internal storage of dates are in U.S. format! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-6 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the USER Database Following is a list of the fieldnames and their meanings. Note that in column 1, a lowercase letter appears which indicates what type of field it is. This lowercase letter is one of: s=string, n=numeric, c=character, b=boolean. You'll need to know this information later on when you write your MBBSEXEC programs. Here is the USER fieldname list: s @LASTNAME - User's Last Name s @FIRSTNAME - User's First Name s @MIDDLENAME - User's Middle Name n @ID - User's ID number (NOTE: number only, no '/' char) s @STREET1 - User's Company Name s @STREET2 - User's Street Address s @CITY - User's City s @STATE - User's State or Province s @ZIP - User's Zip Code or other Zone Info s @COUNTRY - User's Country s @FIRSTCALL - Date User First Called the BBS (MM/DD/YYYY) s @LASTCALL - Date User Last Called the BBS (MM/DD/YYYY) s @TIMELAST - Time User Last Called (HH:MM in 24-hr format) s @PASSWORD - User's Password s @DOB - User's Date of Birth (MM/DD/YYYY) s @PHONE1 - User's Home Phone# s @PHONE2 - User's Company Phone# s @CPUTYPE - User's Computer Type [can be overridden with a sysop-defined field. See CPUTYPE_OVERRIDE in Ch 1. s @CONFERENCES - User's Conferences allowed (ie: "abefh") s @MEMODATE1 - User's Memodate #1 s @MEMODATE2 - User's Memodate #2 b @PRIVMSG - Is user allowed to enter Private Messages? b @DELMSG - Is user allowed to delete messages? s @SYSOP_COMMENT - Sysop's Comment about user c @XFERTYPE - User's default file xfer protocol (X,C,1,Y,G,Z,N) c @PERIODTYPE - User's Period Type (D,W,M,Y) b @EXPERT - Expert mode on? b @LOCKED_OUT - Is user locked out? b @COLOR - Is user using ANSI color? b @DISPLAY_MORE - Does user want the "- - More - -" prompt? b @ERASE_MORE - Does user want the "- - More - -" prompt erased? b @HOTKEYS - Is user using single-keystroke commands? n @LINES_PAGE - User's number of lines per page n @LEVEL - User's security level n @UPLOADS - Number of uploads user performed n @DOWNLOADS - Number of downloads user performed n @CPS - User's adjusted Characters Per Second transfer rate n @UDRATIO - User's Upload/Download ratio n @TTL_CALLS - User's total number of calls n @REMAINING - User's time remaining for the last call n @REMAINING_PERIOD - User's time remaining for the period n @K_UL - Kbytes User performed in Uploads n @K_DL - Kbytes User performed in Downloads n @PERIOD_DL - User's downloads this period n @PERIOD_K_DL - User's Kbyte downloads this period n @DL_THIS_PERIOD - Downloads user performed this period MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-7 Field Names for the USER Database n @K_DL_THIS_PERIOD - Kbytes in downloads user performed this period n @DAILY_TIME - Daily Time allowed on system n @DAILY_DL - Daily downloads User is allowed n @DAILY_K_DL - Daily Kbyte downloads User is allowed b @PRIVACY - Is user's Privacy switch on? s @FILE_U_AREAS - File upload areas allowed s @FILE_D_AREAS - File download areas allowed s @FILE_L_AREAS - File list areas allowed s @MSG_R_AREAS - Message Read areas allowed s @MSG_W_AREAS - Message Write areas allowed s @MSG_L_AREAS - Message List areas allowed s @DISP_CMDS - Display commands allowed s @I - User's interests c @COMPRESS - User's compression type (A,Z) n @PUBLM - Number of public messages entered by user n @PRIVM - Number of private messages entered by user b @DELETED - Is this user deleted? c @DATEFORMAT - User's Date Format (U=US, E=Europe) b @SUB_FILEDEL - Subtract upload credit when a user deletes a file? s @FREE_DL_AREAS - Specify the area(s) (A-Z) which a user can download from without being counted toward their UL/DL ratio n @FREE_DOWNLOADS - The number of FREE downloads the user has performed n @RJEJOBS - The number of RJE jobs the user submitted. n @SENDNULLS - Number of Nulls to send after CR/LF (usually 0) can range from 0 to 255. c @FILELIST_PREF - The user's FileList preference (C=Chronological order, R=Reverse Chronological Order). No defaults. b @REUSE - Y/N or TRUE/FALSE to indicate that this ID (record) can or cannot be reused if deleted. Note that in order for this to be reused, the REUSE_DEL keyword in your STARTUP.n file(s) must also be set to Y. n @MSGGROUP - For those using the extended MsgBase module, accesses the user's message group field. n @FILEGROUP - For those using the extended FileBase module, access the user's file group field. c @TYPE - Magnum supports two kinds of user accounts. USER and MAIL. This field holds either U for USER or M for MAIL. n @FILEBASE - The LAST FileBase the User was in, or the default FileBase to jump to the next time the user logs on. n @MSGBASE - The LAST MsgBase the User was in, or the default MsgBase to jump to the next time the user logs on. b @RMAIL - Y/N or TRUE/FALSE to indicate that this user can or cannot use the remote mail system. If TRUE, the user can enter a message to another user on another Magnum system supported by the Sysop. If FALSE, the user cannot enter or reply to remote mail messages. Note that field types (s,n,c,b) indicate what type field is being described by the fieldnames. For type 'b' (boolean), it will hold one of two things - TRUE or FALSE (or Y or N, or 1 or 0). We suggest using the words TRUE or FALSE for these fields. For example: @PRIVACY = FALSE MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-8 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the USER Database The n (numeric) fields hold digits only. For example: @UDRATIO = 20 The c (character) fields hold a single character and must be within single quotes when comparing or assigning. For example: if(@compress == 'A') { @COMPRESS = 'Z' } Finally, the s (string) fields holds a string of characters and must be within double quotes when comparing or assigning. For example: if(@firstname == "Richard") { @firstname = "Rick" } Note the 1st parameter of all comparisons must be a valid fieldname. The 2nd parameter can be a fieldname or something you choose to compare. This covers the fieldnames for the USER databases. Next, we'll cover the FILE, MESSAGE, RJE and UTILIZ databases, then continue with the syntax and construction of an MBBSEXEC program. IMPORTANT: See the section entitled "Date Fields are Special Cases" MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-9 Field Names for the MSG Database b @DELETED - Is this message deleted? c @CONF - Conference area (A-Z) of message b @PRIVATE - Is this a private message? b @RECEIVED - Has the message been received by addressee? n @FROM - ID of who wrote the message (-1 if from Magnum) n @TO - ID of who the message is to (-1 if for ALL) n @NUM - ID of original addresse (if CC or Forward) n @TIMESREAD - Number of times message was read s @SUBJECT - Message Subject s @DATE - Date of Message (MM/DD/YYYY) s @TIME - Time of Message (HH:MM in 24-hour format) s @EXPDATE - Expiration date of message (MM/DD/YYYY) b @CC - Is this a carbon copy? b @FORWARD - Is this a Forwarded message? b @RECEIPT - Is a receipt wanted for this message? b @REPLIES - Are their any replies to this message? b @ISREPLY - Is this message a reply to another message? s @RCVDATE - Date message was received by addressee (MM/DD/YYYY) s @RCVTIME - Time message was received by addressee (MM/DD/YYYY) s @FILENAME - Ref# or Filename (excluding pathname) of message n @MSGBASE - Indicates MessageBase of message (0-255) (will always be 0 if you don't have the optional extended messagebase module). n @FROM_PSERNUM - Parent Serial# of Sending BBS n @TO_PSERNUM - Parent Serial# of Target BBS b @SENT - Sent (TRUE/FALSE) [if to a different BBS] s @FROM_USERNAME - Full name (string) of originating user s @FROM_FILENAME - Originating System's Filename (REF#) n @FROM_MSGBASE - Originating System's MsgBase (0-255) c @MSGMILC - The MILC character used for this message. NOTE: This field is meant to be used when the serial# of the destination system is not the same as the serial# of the sending system. b @ECHO - Y/N or TRUE/FALSE to indicate that this message is echoable to other systems on the mail network. If not, the message is sent as store/forward only. NOTE: This field is ONLY valid if the serial# of the destination system is not the same as the serial# of the sending system. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-10 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the FILE Database b @DELETED - Is this file deleted? c @AREA - Area file is in (A-Z) b @PRIVATE - Is this a private (password protected) file? c @UL_METHOD - Upload method (X,C,1,Y,G,Z) s @NAME - Name of file (filename.ext) s @PASSWORD - Password of file (if @private == TRUE) s @DATE - Date file was uploaded (MM/DD/YYYY) s @TIME - Time file was uploaded (HH:MM in 24-hour format) s @EXPDATE - Expiration date of file (MM/DD/YYYY) s @BRIEF - Brief explanation of file (string of 76 chars) s @DATELAST - Date Last accessed (MM/DD/YYYY) n @WHO - ID of uploader b @DESFILE - Is a description file available? n @SIZE - Size of file n @DL - Number of downloads n @FILEBASE - Indicates FileBase (0-255) (will always be 0 if you don't have the optional extended filebase module). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-11 Field Names for the RJE Database b @DELETED - Is this record deleted? b @STATUS - Is this RJE Job completed? s @NAME - RJE Jobname Magnum assigned to this Job s @STARTDATE - Date Job started (MM/DD/YYYY) s @STOPDATE - Date Job ended (MM/DD/YYYY) s @PGMNAME - Name of program started s @PARMS - Parms (arguments) passed to program n @USERID - User ID of User that started this Job n @STARTTIME - Time started (seconds from midnight of @STARTDATE) n @STOPTIME - Time stopped (seconds from midnight of @STOPDATE) n @SECONDS - Total run time of job in elapsed seconds n @PRTYCLASS - Priority class of Job when started n @PRTYLEVEL - Priority level of Job when started n @PID - Process IDentification of Job NOTES: - The keywords @STOPDATE, @STOPTIME and @SECONDS have no meaning if @STATUS is FALSE (job is still running). - The keyword @PID has no meaning if @STATUS is TRUE (job is completed). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-12 The MBBSEXEC Sysop Maintenance Utility Program Field Names for the UTILIZ Database n @NODE - Node number ** See NOTE #1 below s @STARTDATE - Session started (MM/DD/YYYY) s @STOPDATE - Session ended (MM/DD/YYYY) n @STARTTIME - Start time in seconds from midnight n @STOPTIME - Stop time in seconds from midnight n @IDNUM - User idnum for this session n @BAUDRATE - User's baud rate ** See NOTE #2 below n @LEVEL - User's security level n @MSGS_READ - # msgs read this session n @MSGS_WRITTEN - # msgs written this session n @FILES_UL - # files uploaded this session n @FILES_DL - # files downloaded this session n @RJEJOBS - # RJE jobs started this session n @SERIALNUM - Serial# of session (not parent#) n @TTLTIME - Ttl time of session (seconds) ** See NOTE #3 below NOTE #1: When processing the UTILIZ database, if the @NODE value is a negative number, it indicates the session was terminated due to dropped carrier. If the @NODE value is negative, simply multiply by -1 to obtain the correct node number. If the @NODE value is negative (dropped carrier), information in the record may be worthless if the drop of carrier took place prior to the user actually logging on. To find out if the user actually logged on, the @BAUDRATE value should be non-zero. If the @BAUDRATE value is zero, this record is to be disregarded. NOTE #2: When processing the UTILIZ database, if the @BAUDRATE value is a negative number, it indicates the connection was established with modem error correction (ie: MNP, LAP, etc). If the @BAUDRATE value is negative, simply multiply by -1 to obtain the correct baudrate. If the @BAUDRATE value is zero (0), the entire record is to be discarded (ignored) because the session ended due to dropped carrier prior to the user actually logging on. NOTE #3: When processing the UTILIZ database, the @TTLTIME variable is not part of the database, but is derived by MBBSEXEC.EXE by taking into consideration the @STARTDATE, @STARTTIME, @STOPDATE and @STOPTIME parameters. @TTLTIME is expressed as the total number of seconds the user was online. @TTLTIME is a "read-only" variable. You cannot use this variable to assign a value to (ie: must not appear on the left side of an = sign). Please note that the UTILIZ.DAT database will not exist unless the TRACK_UTILIZATION parm in your STARTUP.x file(s) is set to Y. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-13 Syntax and Construction of an MBBSEXEC program An MBBSEXEC program consists of an ASCII text file containing MBBSEXEC program statements. The physical limitations of the file are: - Each text line can be up to 120 characters in length - Each text line must be terminated by a CR/LF pair (automatic with most text editors) - The entire file must not exceed 64,000 bytes (file size). We've seen an example of a small MBBSEXEC program earlier, but we'll review the basic skeleton here again: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: MUSIC.LOG #DATABASE: USER #START . . . ! This is a comment . . . #STOP The #CONFIG_FILE: statement tells MBBSEXEC the name of the initialization file used by the BBS program (MBBS.EXE). The #LOG_FILE: statement tells MBBSEXEC what file to write "log" statements to. The #DATABASE: statement tells MBBSEXEC which database to work on (USER, MSG, FILE, RJE or UTILIZ) - this is important because you'll also note that some of the fieldnames for the 5 databases are identical - it is the #DATABASE: statement which makes the distinction. NOTE: For those using the Magnum 'Extended MessageBase' or 'Extended FileBase' modules, you can specify which MessageBase or FileBase file to process (not to be confused with the @MSGBASE field or @FILEBASE fields above) by specifying the #DATABASE statement as follows (via examples): #DATABASE: MSG defaults to main Message Database #DATABASE: MSG5 uses Message Database 5 #DATABASE: MSG109 uses Message Database 109 #DATABASE: MSG0 same as "#DATABASE: MSG" #DATABASE: FILE same as "#DATABASE: FILE0" #DATABASE: FILE76 uses File Database 76 Be advised that this statement is used only to determine the filespec of the datafile for that message or file base. If you're using MSG.DAT in the session directory for each of your message bases, then MSG and MSG110, for example, are mutually exclusive. If any of the FILE or MSG databases are used for more than one MSG or FILE database, use the @MSGBASE or @FILEBASE keywords MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-14 The MBBSEXEC Sysop Maintenance Utility Program Syntax and Construction of an MBBSEXEC program (fields) within your .MEX programs to narrow down which file or message base you wish. NOTE: For users of the Extended FileBase or MsgBase modules, you may also use the follwoing #DATABASE statements: #DATABASE: FILE* #DATABASE: MSG* When the asterisk character (*) is used as above (FILE* or MSG*), it tells MBBSEXEC to apply your .MEX program to EVERY FILE and MSG database on the system! This comes in handy for those who do not keep their message and/or file database in a single database file. MBBSEXEC will always start with your main database, then restart with the next, then the next, etc with this method. The #START and #STOP statements tell MBBSEXEC that all statements appearing inbetween are to be executed (carried out) for every record in the database. Note that any statement starting with an exclamation mark (!) is a comment and will be ignored by MBBSEXEC. Comments merely serve as useful notes to yourself. The periods above (.) are not statements but merely for illustrative purposes - these periods (.) would represent actual program statements in an MBBSEXEC program file. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-15 The Assignment Statement The Assignment statement is the simplest of all. Basically, an assignment statement places a value you supply into one of the fields. For example, the statement: @memodate1 = "06/30/1990" would assign the string "06/30/1990" to the @memodate1 field of the user database. You'll probably want to have assignment statements execute only if an IF statement is true, otherwise it will be assigned to all users. The above example is an example of string assignment. If the field is a string field, then the assignment part must be enclosed within double quotes. Another example: @file_l_areas = "abchjk" An example of an assignment statement for a character field would be enclosed in single quotes. For example: @compress = 'Z' An example of an assignment statement for a numeric field is probably the simplest of the assignment statements. For exmple: @level = 6 Finally, an assignment statement for a boolean field is either TRUE or FALSE. For example: @color = TRUE Date fields are handled differently - BE SURE TO VIEW THE SECTION ENTITLED "DATE FIELDS ARE SPECIAL CASES"! For any assignment statement, look at the database fieldname earlier in this chapter and note if it's a string, character, numeric or boolean field and follow the assignment rules for that type of field. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-16 The MBBSEXEC Sysop Maintenance Utility Program Comparison Statements (IF) The Comparison (or IF) statements are somewhat more comprehensive to grasp. If you're experienced in the C programming language it will help you a great deal. Keep in mind the rules you've learned for the 4 kinds of datatypes described earlier (string, numeric, character and boolean). The same rules apply for comparisons (ie: strings to be compared with double-quoted strings, characters to be compared with a single-quoted character, numerics to be compared with digits, and booleans to be compared with TRUE or FALSE). There are 7 kinds of comparators for comparison statements. A comparator tells MBBSEXEC what kind of comparison you wish performed on the two fields being compared. The comparators are: == Test for equality != Test for inequality >= Test for greater than or equal <= Test for less than or equal > Test for greater than < Test for less than ~ Test if string2 is within string1 (string comparisons only) The following example tests for a user id of 177 and deletes the user if a match occurs. if(@id == 177) { @deleted = TRUE } The following example tests for all callers whose last call to the BBS was 90 days ago or more and deletes them if true. if(@lastcall < @today - 90) { @deleted = TRUE } NOTE: Nested IF statements are allowed. See "MBBSEXEC Advanced Features" later in this chapter. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-17 Branch Statements (GOTO) There will be times when you wish to test for a certain condition and skip program statements if the condition tests true. Since MBBSEXEC is a simple programming language without AND and OR operators, the GOTO statement can emulate AND and/or OR conditions. The GOTO statement consists of 2 parts: the actual GOTO statement, and a LABEL as the target of a GOTO. The syntax of a GOTO statement is: goto(labelname) The Syntax of a label is: labelname: The two things to remember are that the GOTO itself must be followed by a label name enclosed within parenthesis, and the actual label name must appear elsewhere within the #START and #STOP statements and must end with the colon (:) character. As an example, suppose you want to increase the security level of level 5 users to level 6 only if they've entered 2 or more public messages. The following example demonstrates this: if(@level != 5) { goto(skipit) } if(@publm >= 2) { @level = 6 log("Upgraded from level 5 to 6: /",@ID) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("# Public Msgs entered: ",@publm) log("-------------------------------") } skipit: In the above example, the first IF statement tests the user level. If it is not a user level of 5, then the IF condition is TRUE and takes the branch to the SKIPIT: label. We want to perform this branch because we want the following statements executed for only level 5 users. If they are a level 5 user, the first IF will test out FALSE and will not take the branch - instead, it will fall through to the next IF statement which tests for the number of public messages entered. If 2 or more public messages are entered, the user's security level is changed to 6 and we write a summary of the change to the log file. The above programming statements show how an AND condition can be emulated by using a couple of IF statements and a GOTO. In a higher level language such as C, the same thing could be accomplished without a GOTO and with only 1 IF statement - ie: if((@level == 5) && (@publm >= 2)) but since this is a simple programming language, we must use the 2 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-18 The MBBSEXEC Sysop Maintenance Utility Program Branch Statements (GOTO) IF statements in conjunction with a GOTO. For those with programming experience, IF statements can be nested in order to emulate an AND statement: if(@level == 5) { if(@publm >= 2) { @level = 6 log("Upgraded from level 5 to 6: /",@ID) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("# Public Msgs entered: ",@publm) log("-------------------------------") } } The above example (using nested IF statements) demonstrates a cleaner way of doing things, and eliminates the need for a GOTO statement. An important thing to keep in mind is the testing of a field for NUL (if there's anything in a field). These can all be accomplished by having the second parameter of an IF statement as 0. For example, if you wanted to delete all users whose memodate1 field is older than today, you would first need to test if the memodate1 field had a value in it: if(@memodate1 == 0) { goto(skipit) } if(@memodate1 < @today) { @deleted = TRUE } skipit: All fields pertaining to dates are handled as special cases. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-19 Date Fields are Special Cases Date fields are handled differently for comparisons than assignments. As a matter of fact, date fields are handled as numerics during comparison, and as strings during assignments. For example, the statement: if(@lastcall < @today - 90) { . . } is handled internally by treating the @lastcall and @today fields as numerics. This way, MBBSEXEC can perform numeric arithmetic and comparison by first converting date fields to numeric numbers representing number of days since Jan 1, 1980. You needn't concern yourself with this, other than the fact that you need to know that dates are handled as numerics for comparison purposes. When assigning something to a date field, the assignment is handled as a double quoted string as expected: @memodate1 = "06/01/1990" The @memodate1 and @memodate2 fields can also accept the @today field + or - a value. For example, the following might be used to set expiration dates of 6 and 12 months for a subscription BBS: @memodate1 = @today + 183 @memodate2 = @today + 366 Another .MEX file might run as a daily maintenance program which checks these @memodate fields for expiration and act accordingly. It is important to remember the date rules. In other words, you can't compare a date field against a quoted string, but you can compare it to something like @today-90 and you can assign a string such as "06/01/1990" to a date field (and can use the exception of assigning with the @today +/- n). REMINDER: ALL DATES ARE STORED AND ENTERED IN U.S. DATE FORMAT!! DO NOT USE EUROPEAN DATE FORMAT WHEN WRITING YOUR .MEX FILES!! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-20 The MBBSEXEC Sysop Maintenance Utility Program Mathematics Finally, mathematics can be performed within MBBSEXEC program statements as we've seen with the "@today - 90" example of subtraction. The mathematical operators which are supported by MBBSEXEC are: + Addition - Subtraction / Division * Multiplication % Modulus For those unfamiliar with Modulus, it simply means "remainder". For example, 5 divided by 3 (or 5/3) is 1, while 5 modulus 3 (or 5%3) is 2. In other words, 3 goes into 5 one time (division) with a remainder of two (modulus). You may use arithmetic on any numeric field for assignment, or date field for comparison. For example, to add 10 minutes to a user's daily time would be accomplished with: @daily_time = @daily_time + 10 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-21 Processing a Single User Instead of the Entire Database Instead of looping through every user in the USER database, there may be times you wish to process only a single user instead. With what you've learned above, you know that we can check for a certain user id and process statements only if that id matches. If all you wanted to do was process a single matching user id, this method would be a tremendous waste of time since MBBSEXEC would loop through every record in the database, only to process changes for one user. This Section explains a feature built into MBBSEXEC which will accomplish just that. Single-user processing is currently limited only to the USER database (USER.DAT and USER.KEY files), and must be the FIRST database processed (won't work if you've processed FILE or MSG database first in the same .MEX file). There are 2 ways of accomplishing single-user processing. The first way is to provide the user's ID number on the #START line. For example: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: PRN #DATABASE: USER #START 212 . . . #STOP The above would process the user with user id 212 only. The second method is to supply the user id to process on the program command line: MBBSEXEC UPDT 212 which would process the UPDT.MEX file for user id 212 only. This method works as though you had a statement of: #START 212 in your .MEX file. Remember, single-user processing only works on the very first #START statement encountered in the .MEX file, and it must be part of the USER database - the FILE, MSG, RJE and UTILIZ databases ignore this parameter. One great example of single-user processing would be the following: Suppose you ran a subscription BBS and wanted to update users who've subscribed to a higher security level with more capabilities on the system. Just as an example, your .MEX file might look something like this: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: PRN MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-22 The MBBSEXEC Sysop Maintenance Utility Program Processing a Single User Instead of the Entire Database #DATABASE: USER #START @level = 50 @msg_r_areas = "abcdefghijklmwxz" @msg_w_areas = "abcdefghijklm" @msg_l_areas = "abcdefghijklmz" @file_u_areas = "mn" @file_d_areas = "abcdefghijklmnz" @file_l_areas = "abcdefghijklmnz" @daily_time = 90 @periodtype = 'w' @udratio = 0 #STOP The above .MEX file would normally loop through the entire USER database and change EVERY user to the above criteria since there are no IF or GOTO statements in this particular file. Assuming the above statements are stored in filename LVL50.MEX, the following invocation of MBBSEXEC would in fact, change EVERY user in the USER database to the above criteria: MBBSEXEC LVL50 If the #START statement in the LVL50.MEX file had a number after it, only the user id matching that number would be processed. However, the following invocation of MBBSEXEC would change only one user, user 321 for example: MBBSEXEC LVL50 321 Note that by supplying a USER id on the program command line, it will override a hard-coded user id (ie: one that's part of a #START statement). With this crude example, you can see the power of having separate .MEX files for different security levels. To change anyone's security level at anytime, including all the fields you've associated with a particular security level, simply adapt the above method to your particular needs. This technique can also be used in conjunction with Magnum's @E0 MILC command to update a user ONLINE! Because it's too easy to accidentally forget the user-id parameter on the program line - a mistake could cause havoc in your user database. One safeguard against this is to use a .CMD file for all of your single-user updates. The .CMD file might have a name like UPDT.CMD and contain the following statements: IF %1 == . GOTO SYNTAX MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-23 Processing a Single User Instead of the Entire Database IF %2 == . GOTO SYNTAX MBBSEXEC %1 %2 GOTO DONE :SYNTAX ECHO USAGE: UPDT MEXFILE USERID :DONE Now, instead of running the MBBSEXEC program directly to update user 321, you'd use the UPDT command file instead: UPDT.CMD LVL50 321 which would be identical to: MBBSEXEC LVL50 321 However, entering: MBBSEXEC LVL50 would cause complete disaster (forgot the userid), whereas: UPDT LVL50 would echo program usage to you instead of running the MBBSEXEC program. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-24 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC 'Simple' Summary You've now learned the language of MBBSEXEC. It is a straight forward, simple programming language with much power. The uses for MBBSEXEC are limited only by your imagination. For example, you could put together a mailing list of all level 10 users, or a mailing list of all people in a certain zipcode. In addition to what you've learned, you can also have multiple "programs" in the same MBBSEXEC program file. For example, to upgrade all users to level 6 from level 5 who've entered 2 or more public messages, and delete all callers who haven't called in the past 90 days, AND delete all messages older than 90 days, AND change the expiration date of all files in area B to "06/01/1990", the following file of MBBSEXEC statements would accomplish the task: ! ! Update Users from level 5 to level 6 ! #CONFIG_FILE: E:\GS\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: USER.LOG #DATABASE: USER #START ! Change Level 5 users to 6 if 2 or more public messages entered if (@level != 5) { goto(skip) } if (@publm >= 2) { @level = 6 @daily_time = 45 @file_u_areas="egi" log("Upgraded from level 5 to 6: /",@ID) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("# Public Msgs entered: ",@publm) log("-------------------------------") } skip: if(@lastcall == 0) { goto(skip_the_rest) } if(@lastcall < @today - 90) { log("deleting due to lack of calls in 90 days: /",@id) log("Lastname: ",@lastname) log("Firstname: ",@firstname) log("Lastcall: ",@lastcall) @deleted=true MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-25 MBBSEXEC 'Simple' Summary log("---------------------------") } skip_the_rest: #STOP ! !----------------- Now process message database --------------------- ! #CONFIG_FILE: E:\GS\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: MSG.LOG #DATABASE: MSG #START ! skip files with existing expiration dates if (@expdate != 0) { goto(skipexp) } ! ---------- skip if conference area is the "file description" ! ---------- conference area. This area will vary from installation ! ---------- to installation. In our case, 'X' is our conference ! ---------- area for file descriptions. if (@conf == 'X') { goto(skipexp) } if (@date < @today-90 ) { @deleted = TRUE log("Deleted Message: ",@filename) log("Subject: ",@subject) log("--------------------") } skipexp: #STOP ! !----------------- Now process file database --------------------- ! #CONFIG_FILE: E:\GS\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: FILE.LOG #DATABASE: FILE #START MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-26 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC 'Simple' Summary if (@area == 'B') { @expdate = "06/01/1990" log("Changed expiration date of: ",@name) log("Description: ",@brief) log("---------------------------") } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-27 MBBSEXEC 'Simple' Summary To summarize, MBBSEXEC is a very powerful, yet simple programming language. But you must remember that MBBSEXEC only performs part of the job in some instances. Anytime you have a statement such as: @deleted = TRUE the actual file or message is not really deleted - it's only marked as deleted. To really delete the file, you'll need to log onto your BBS and go into the SYSOP menu. Choose the [S]tatus of Databases command which will perform most of the actual deletions. Next PACK the databases to finish off the deletions. Note that the USER database is not packable. NOTE: YOU MUST BE THE ONLY ONE ONLINE TO PERFORM A PACK OF THE DATABASES! If you assign TRUE to @deleted in the USER database AND you've configured MAGNUM to reuse deleted ID's for new users, the next person that logs on will get that deleted ID. If you assign TRUE to @deleted in the FILE database, files will be deleted whenever someone tries to do a [L]ist of the area the deleted file(s) is in. If you assign TRUE to @deleted in the MSG database, messages are not deleted unless you do a [S]tatus of Databases command from within the sysop menu, and a Pack on the database. If you assign TRUE to @deleted in the RJE database, that record is only marked as deleted, not actually deleted. There is no PACKING facility available for the RJE database due to the nature of the RJEMONIT.EXE daemon process requiring access to the database at any given time! In any event, [S]tatus of Databases and Pack commands from within the Sysop menu will go ahead and perform the actual deletions. IMPORTANT: Running MBBSEXEC.EXE when your BBS is SHUT DOWN (not running) will result in slightly faster execution of MBBSEXEC.EXE. We hope you'll find many good uses for MBBSEXEC, but you must remember to make a backup of your *.DAT and *.KEY files PRIOR to running any MBBSEXEC programs. If you do not have a backup of your databases and run into trouble with the MBBSEXEC program then DON'T bother calling us - there's nothing we can do for you! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-28 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features MBBSEXEC -- ADVANCED SECTION Up until now, we've introduced MBBSEXEC.EXE to you as a simple programming language. If you're not a programmer, what you've learned until now should be just enough to get you started writing .MEX programs which will suit your needs. However, if you are an experienced programmer, preferably in the C programming language, then you'll enjoy this "Advanced Features" section. Non-Programmers may choose to omit the remainder of this chapter, but are welcome to continue. With the Advanced features incorporated into MBBSEXEC, you can have Nested IF() statements, optional ELSE statements for your IF statements, and WHILE() statements. Functions also exist to EXIT() a .MEX program in progress, get INPUT() from users, and perform logging to the console with clog() statements, logging to a binary file with the blog() statement, or logging to a string with the slog() statement. You can run external programs with the SYSTEM() command, create your own .MEX functions and CALL() them, save and restore data which can be used by MSESSION and much more! We'll start out describing the easiest statements and techniques for the sake of those new (or with little exposure) to programming, and progressively work our way into more advanced techniques. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-29 MBBSEXEC Advanced Features - the EXIT statement You can exit your .MEX file at anytime with the following statement: EXIT(x) where 'x' is the value to be assigned to the exit code upon exit. Whenever an EXIT(x) statement is executed, MBBSEXEC.EXE will end. The value of the exit code (x) can be tested for if MBBSEXEC was started from a .CMD file (using the ERRORLEVEL variable). A valid EXIT(x) statement might look something like this: EXIT(5) NOTE: Without the EXIT(x) function, MBBSEXEC.EXE always ends with an exit code of 0 or 1. If it ends with 0, it means everything went ok. If it ends with 1, it means it terminated due to some error condition (the cause of the error is displayed upon the abnormal termination). You should keep this in mind when using the EXIT(x) function. For example, you might want to use EXIT(x) where 'x' is a value of 2 or above. The valid range is 0 to 255 and is not checked by the MBBSEXEC program. You can use a @TALLYx variable in place of the 'x' (@TALLYx is explained later). The EXIT(x) function is meant to be used as part of an IF statement. For example, the following illustrates exiting the .MEX file at the 100th record: . . if(@thisrec == 100) { exit(5) } . . Naturally, you'll want to exit() your .MEX program based on some other meaningful information, such as finding the first occurence of a particular last name. @THISREC used above is explained later. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-30 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Special Fields in USER database Special Fields in the USER database Certain fieldnames of the USER database area have been designated as being "special". These "special" fields are those which hold up to 26 characters (the letters of the alphabet). The "special" fields are: @FILE_U_AREAS @FILE_D_AREAS @FILE_L_AREAS @MSG_R_AREAS @MSG_W_AREAS @MSG_L_AREAS @CONFERENCES @FREE_DL_AREAS @DISP_CMDS You've learned how to make simple assignments to these fields with statements such as: @FILE_D_AREAS = "ABCFGH" With the new enhancement added to this version, you can ADD areas TO or DELETE areas FROM these special fields. For Example, if the field @FILE_D_AREAS already contains "ABCFGH", and you wish to add areas I and J, you would accomplish it with the following statement: @FILE_D_AREAS = "+IJ" The value of @FILE_D_AREAS would now contain "ABCFGHIJ". If you wish to delete areas B and C from @FILE_D_AREAS (assume it currently contains "ABCFGH"), you would accomplish it with the following statement: @FILE_D_AREAS = "-BC" The value of @FILE_D_AREAS would now contains "AFGH". Summarizing, if you wish to assign to one of these special fields, simply assign as you have in the past. However, if you wish to add to the field, simply make the '+' character the very first character in your assignment string. To remove from the field, simply make the '-' character the very first character in your assignment string. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-31 MBBSEXEC Advanced Features - #LOG_FILE: #LOG_FILE: If the parameter to the #LOG_FILE: statement is "STDOUT" (without the quotes) as the name of your log file, then all output will be written to standard output (the console). When written to standard output, the "Record: xxx of yyy" display will be supressed, and if you run MBBSEXEC.EXE as a child process of the BBS, then the remote user will be able to view the output. If running MBBSEXEC.EXE as a standalone program (not from the BBS), if the #LOG_FILE: is STDOUT, then output is redirectable (ie: with the OS/2 ">" redirection symbol). If the filename supplied to the #LOG_FILE: statement is appended with a ",A" (without the quotes) after the filename, it will open up the file for Append. For example, the statment: #LOG_FILE: USER.LOG,A will open USER.LOG as the output file and append its output to the end of the file. If the ",A" is omitted, the file specified in the #LOG_FILE: statement will be deleted if it exists prior to its use. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-32 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters The log() statement is the key to generating Mailing Labels, Form Letters and Reports. To accomplish this, you'll need to become familiar with the enhanced capabilities of the log() statement. Enhanced LOG statement capabilities: The ENHANCED format of the LOG statement is: LOG(PARM1, PARM2, ... PARMn) where: The PARMx arguments can consist of any combination of field variables relating to the current database and/or quoted strings. Examples: log("Name: ",@lastname,", ",@firstname," ",@middlename) log(" ID: /",@id," Last called on ",@lastcall) log("--------------") You can even print mailing labels: log(@firstname," ",@middlename," ",@lastname) log(@street1) log(@street2) log(@city," ",@state,", ",@zip) log(@country) log("") The above assumes 5 printable lines per label, the 6th line being the space separating one label from the next. With the information you've learned so far, you can expand on these capabilities in order to produce form letters. A form letter would typically consist of many log() statements contain quoted strings as the message body, with a few '@' variables thrown in where appropriate. Generally, form letters will be written to users matching specific criteria, skipping those who don't match. For illustrative purposes, a simple form letter generated to all users of a subscription board who are about to expire within the next 30 days might look something like the following: #CONFIG_FILE: D:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: PRN #DATABASE: USER #START if(@memodate1 == 0) { goto(skipit) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-33 MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters } if(@today + 30 > @memodate1) { log("") log("") log("") log("") log("") log(" ",@today) log(" ",@firstname," ",@middlename," ",@lastname," (ID: /",@id,")") log(" ",@street1) log(" ",@street2) log(" ",@city," ,",@state," ",@zip) log("") log("") log(" Dear ",@firstname," ",@lastname) log("") log(" Our records show that your BBS subscription is about to") log(" expire on ",@memodate1,".") log("") log(" Don't miss out! Get uninterrupted service by renewing your") log(" BBS Subscription today!") log("") log("") log(" Sincerely,") log("") log("") log("") log("") log("") log(" John Sysop") log("") log(@\12) } @tally1 = @tally1 + 1 skipit: if(@thisrec == @hirec) { log(@tally1," letters generated",@\12) } #STOP In the above example, please note that the @\12 parameter translates to a FormFeed character (tells printer to advance to the top of next page). In order to send characters to your log file or device (ie: printer) which cannot be entered by pressing a keyboard key, you may still send that character to the log by using its decimal equivalent. The decimal equivalent for FormFeed is 12, thus @\12 tells the log() statement to send a FormFeed to the printer. The format is the following: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-34 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters @\x where 'x' is the decimal equivalent of the character you wish to send to the log. This is an ideal way to send escape sequences to your printer in order to change fonts, print size, etc. For example, an escape sequence of "<Esc><Ctrl-X><Ctrl-Y>Hello" would be entered as follows: log(@\27,@\24,@\25,"Hello") The following ADVANCED KEYWORDS allow you to produce reports: @LOREC - indicates record 0 (the first record in a database) @HIREC - indicates record X (the last record in a database) @THISREC - indicates the current record being processed @TALLY0 - Tally counter number 0 @TALLY1 - Tally counter number 1 . . @TALLY98 - Tally counter number 98 @TALLY99 - Tally counter number 99 The @TALLYx counters can be used to count whatever you wish, or can be used for other purposes such as flags. With the introduction of the modified/enhanced LOG statement, you can actually generate FORM LETTERS, and with the introduction of the new KEYWORDS above, you can generate detailed reports! Initially, upon start of processing, @LOREC is set to 0, @HIREC is set to the highest record number, @THISREC varies with the current record number, and the @TALLYx counters are set to 0. The @HIREC, @LOREC and @THISREC variables are to be used for comparisons only, they must not be used as the target of an assignment statement. The @TALLYx variables are to be used however you wish. NOTE: The @LOREC, @HIREC and @THISREC variables are typically used to generate report headers and summaries at the beginning and ending of processing. Please note that the use of these will cause an increase in your processing time! The following example will print mailing labels for all level 30 users on the system. When finished with the labels, it will generate a small report stating how many mailing labels were generated and what percentage of the users on the system are at level 30. Each label is assumed to consist of 5 printable lines, and 1 blank line separating the labels. The header and summary will each consume 1 label: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: LEVEL30.LOG #DATABASE: USER #START MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-35 MBBSEXEC Advanced Features - Labels/Letters/Reports - Counters if(@thisrec == @lorec) { log("The following is a list of Level 30 Users") log("") log("") log("") log("") log("") } if(@level==30) { log(@firstname," ",@middlename," ",@lastname) log(@street1) log(@street2) log(@city,", ",@state," ",@zip) log(@country) log("") @tally5 = @tally5 + 1 } @tally9 = @tally9 + 1 if(@thisrec == @hirec) { log("End of list for Level 30 users") log("There were ",@tally5," users printed") log(@tally9," total records processed") @tally5 = @tally5 * 100 @tally0 = @tally5 / @tally9 log(@tally0,"% of the users are at Level 30") log("") log("") } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-36 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Strings, Binary & Console Output Much like the @TALLYx variables available to you, there are also string variables available to you: @STRING0 @STRING1 . . @STRING99 Each of these variables is capable of holding up to 100 bytes. You can assign any other string variables to/from these @STRINGx variables. You can use these variables however you please. In addition to the enhanced LOG() statement, an SLOG() statement also exists which writes its output to a @STRING variable rather than the log file. The format is: SLOG(x,parm1,...,parmn). It is identical to the LOG() statement except that the first parameter (x) tells the SLOG() statement which @STRINGx variable to write to. For example, the statement: slog(5,@firstname," ",@middlename," ",@lastname) would result in writing the above parameters to @STRING5. When the statement completes, @STRING5 might hold a value such as "John S Doe". The slog() statement was necessary for this type of combination because string variables do not have an append operation such as '+'. Note that a CR/LF (carriage return/linefeed) is NOT appended to the end of the string. log() statements append a CR/LF to the output. slog() and blog() statements do not. If you wish to create your own binary (random access) file as output, you can do so with the BLOG() statement. The BLOG() format is: BLOG(x,parm1,...,parmn). It is identical to the writing the LOG() statement except that the first parameter (x) tells the BLOG() statement how many bytes to write. For example, the statement: blog(50,@firstname," ",@middlename," ",@lastname) would result in writing 50 bytes to the output file (the output file is the filename in the #LOG_FILE statement). If the result is longer than 50 bytes, only the first 50 bytes are written. If the statement being written is shorter than x, the difference is padded with nulls (binary 0's). By using blog() statements instead of log() statements, it is possible to create your own binary (random access) output files this way. Note that CR/LF (carriage return/linefeed) are NOT appended to blog() statements. Only the log() statement appends a CR/LF. When opening an existing binary log file for append mode, do not use a ",A" (without quotes) after the #LOG_FILE file name. Instead, use ",U" (without quotes) to indicate binary update mode. This simply tells MBBSEXEC not to write the "* * * Append * * *" string which it normally does when ",A" is used. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-37 MBBSEXEC Advanced Features - Strings, Binary & Console Output When using blog() statements, take care not to use log() statements! Note that the @\x variable is available for log(), slog() and blog() statements. If you wish to print a message to the console (regardless of the value of the #LOG_FILE paramater), you can use the clog() statement. It's operation is identical to that of the log() statement except that its output always goes to the console, whereas the log() statement's output always goes to the file specified in the #LOG_FILE statement. For technical users, the output of the clog() statement is printed to the console via stderr (ie: can be redirected with "2>filename"). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-38 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - the INPUT() statement Your .MEX programs are capable of interacting with the user in order to receive user input. User input can be directed to a @STRINGx or @TALLYx variable. The format of the INPUT() statement is as follows: INPUT("input text",@TALLYx) or INPUT("input text",@STRINGx) When the MBBSEXEC.EXE program executes an input statement, it prints the contents of "input text" on the console and waits for the user to type their input. An example of an input() statements follow: input("What is your name => ",@string1) input("How old are you => ",@tally1) Input() statements might generally be found in .MEX files that search for some criteria without having the need to edit the .MEX file every time the criteria changes. For example, to search for one or more occurrences of a certain last name, the following statements might be used: #START if(@thisrec == @lorec) { input("Lastname to Search For => ",@string1) } ! ! clog("Comparing ",@\34,@lastname,@\34," and ",@\34,@string1,@\34) ! if(@lastname == @string1) { clog("Name: ",@lastname,", ",@firstname," ",@middlename) clog(" ID: /",@id) clog("From: ",@city," ",@state," - ",@country) clog("Last Called on ",@lastcall) clog("- - - - - - - - - - - - - - -") input("Search for Next Occurence (Y/N) => ",@string2) if(@string2 == "N") { exit(0) } } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-39 MBBSEXEC Advanced Features - the WHILE() statement Much like the IF() statement, the WHILE() statement is identical in format: IF(expression) { . . } WHILE(expression) { . . } The only difference between the two is that when an IF() statement ends (matching } found), the program continues with the next statement. With a WHILE() statement, the WHILE() loop repeats continuously until (expression) becomes false. For exmple: @tally5 = 1 while(@tally5 != 0) { input("Enter a number (0 to quit) => ",@tally5) clog("You picked ",@tally5) } clog("Ok - the WHILE() loop is now over!") The reason the WHILE() statement is similar is because if (expression) is TRUE, then the statements following, enclosed in { and } are executed. If (expression) is FALSE, program execution continues with the statement following the } brace which matches the { brace on the WHILE() line. The difference between IF() and WHILE() when (expression) is TRUE is that the WHILE() loop repeats itself until (expression) becomes FALSE. This was easily demonstrated with the example above. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-40 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - The } ELSE { statement As mentioned earlier, IF() statements can have matching ELSE statements. The format of an ELSE statement is: } ELSE { all on one line. Each ELSE matches up with the matching { of an IF() statement. And because IF() statements can be nested, so can ELSE statements: if(expression) { . . if(expression) { . . } else { . . } } With the introduction of the ELSE statement, we can simplify many things. For example, the following statements: if(@level > 10) { . . goto(done) } . . done: Could be replaced with: if(@level > 10) { . . } else { . . } thus eliminating the need for the GOTO statement and its associated label alltogether. NOTE: The } ELSE { statement can also be replaced with ELSE (no brackets). Should you desire to use ELSE without the brackets, MBBSEXEC.EXE will internally add the brackets for you. Whether you use these brackets or not is entirely up to you. Some people argue MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-41 MBBSEXEC Advanced Features - The } ELSE { statement that the use of brackets improves readability while others argue that the brackets decrease readability. Nesting levels ( { and } within other { and } ) can be up to 200 levels deep. Extreme caution must be taken when using the GOTO statement when inside a { and } pair or when branching to another { and } pair. For example, in a nested IF ... ELSE statement, it's ok to issue a GOTO to a label within the same matching { and } pair. It's even ok to issue a GOTO from within a { and } pair to the main execution part of the .mex file (ie: not contained within a { and } pair). However, if you're branching to a label within a { and } pair and the GOTO was issued from outside that { and } pair, the results will be highly unpredictable. Example: IF(expression) { . . if(expression) { . badlabel: . goto(ok1) . . ok1: . } . goto(ok2) . } else { . goto(badlabel) . } ok2: Note the branch to ok1 is valid because the label is contained within the same { and } bracket pair as the goto statement. The branch to ok2 is valid because the ok2 label is in the main program body (not within a { and } pair. However, the branch to bad label goes from one { and } pair to another { and } pair and therefore, the results of this branch will be highly unpredictable. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-42 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Indirect Addressing (Indexing) @TALLYx and @STRINGx statements can have the 'x' part of the statement indirectly addressed (indexed) by another @TALLYx variable. For example, the statements: @TALLY5 = 15 @TALLY[5] = @TALLY[5] + 1 the first statement assigns the value 15 to @TALLY5. The second statement indirectly references @TALLY15 by specifying [5] instead of using 15 as part of the name. The [5] specifies to get which tally variable you're looking for from the value stored in @TALLY5. The same logic applies when using [x] with @STRINGx. For example, if @TALLY5 holds the value 15, then @STRING[5] is identical to specifying @STRING15. Since it can become confusing to use @TALLYx statements for your indexes, you may substitute the word @INDEXx in place of @TALLYx. Using the above example, the following become more readable: @INDEX5 = 15 @TALLY[5] = @TALLY[5] + 1 MBBSEXEC internally converts @INDEX to @TALLY - using either method results in an identical result (they both reference the same @TALLYx variable). When using indirect addressing, you can also use pre-increment, post-increment, pre-decrement, or postdecrement. Examples of Pre-Increment: @INDEX5 = 20 log(@TALLY[+5]) is identical to: @TALLY5 = 20 @TALLY5 = @TALLY5 + 1 log(@TALLY21) Examples of Post-Increment: @INDEX5 = 20 log(@TALLY[5+]) is identical to: @TALLY5 = 20 log(@TALLY20) @TALLY5 = @TALLY5 + 1 Pre-Decrement and Post-Decrement work the same way as the increment operation except that it subtracts 1 instead of adds 1, and the '-' sign is used instead of the '+' sign. You can also use a pre-increment or pre-decrement operation AND a MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-43 MBBSEXEC Advanced Features - Indirect Addressing (Indexing) post-increment or a post-decrement operation in the same statement: @TALLY5 = 20 log(@TALLY[+5+]) is identical to: @TALLY5 = 20 @TALLY5 = @TALLY5 + 1 log(@TALLY21) @TALLY5 = @TALLY5 + 1 IMPORTANT: "EQUATED" names can NOT use indirect addressing (indexing)! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-44 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Equating names for @TALLY/@STRING Because it can be very frustrating using @STRINGx and @TALLYx variable names, the EQUATE: keyword has been added. This keyword can redefine the variable names used so that you can use more meaningful names: EQUATE : USER_NAME_FIELD = @STRING10 EQUATE : LEVEL5_COUNTER = @TALLY42 The equated name you plan on using (ie: USER_NAME_FIELD from the above example) must follow certain rules: - The name must not exceed 30 characters in length. - The first character must be alphabetic (A-Z) or the '@' character. - The only valid characters in the name are alpha (A-Z), digits (0-9) and the '_' (underscore), '.' (period), and '@' characters. With the ability to 'equate' your own variable name with a @STRINGx or @TALLYx variable, you can have statements such as: user_name_field = @lastname if(@level == 5) { level5_counter = level5_counter + 1 } which would be identical to: @string10 = @lastname if(@level == 5) { @tally42 = @tally42 + 1 } Note that EQUATE statements may appear anyplace in your .MEX file, however, you cannot use the equated name in your file if it appears before the equate statement. The use of equated names are to appear after the equate statement! You can have up to 200 EQUATE statments (100 for @TALLY0 thru @TALLY99, and 100 for @STRING0 thru @STRING99). Equated names can NOT be indirectly addressed (indexed) using the equated name, but can be indirectly addressed using @STRING[x] or @TALLY[x]. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-45 MBBSEXEC Advanced Features -Writing/calling your own functions To declare a function anywhere in your .MEX file, it must start with the FSTART:FUNCNAME and end with the FSTOP:FUNCNAME parameter. Examples: . . FSTART:func1 . . . FSTOP:func1 . . FSTART:func2 . . . FSTOP:func2 . . Function names (ie: func1, func2, etc) can be any name you wish, up to 30 characters in length. During normal program execution, functions (program statements appearing between FSTART:funcname and FSTOP:funcname statements) are not executed unless explicitly called. You may declare up to 100 functions in any .MEX program (ie: up to 100 functions between any set of #START and #STOP statements). To call a function from within currently executing program statements: . . CALL(func1) . . When MBBSEXEC comes across a CALL() function, it passes control to the function being called. When the function finishes, control is returned to the next statement after the CALL() statement. Calls can be nested up to 100 levels deep. Optionally, if you have a function name in a @STRINGx variable, you can use that @STRINGx variable as the parameter to the CALL() function. Example: @STRING5 = "func1" . . CALL(@STRING5) . . MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-46 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features -Writing/calling your own functions This capability can come in handy when using CLOG() and INPUT() statements to form a menu: @string1 = "func1" @string2 = "func2" @string3 = "func3" @string4 = "func4" clog("0 - Exit Program") clog("1 - Do func1") clog("2 - Do func2") clog("3 - Do func3") clog("4 - Do func4") @tally0 = 0 while(@tally0 == 0) { input("Choice (1-4) => ",@tally0) if(@tally0 == 0) { exit(2) } if(@tally0 > 4) { @tally0 = 0 } } call(@string[0]) To terminate a function early (ie: without processing the rest of the function statements), you may issue the RETURN command: fstart:func1 . . if(expression) { return } . . fstop:func1 Alternately, you can set the @RESULTCODE (a read-only variable) with the RETURN statement when using the format: return(x) where 'x' is a numeric value to be placed in the @RESULTCODE variable. 'x' can also be a @TALLYx variable. If you plan on checking the value of the @RESULTCODE variable after calling a function, it must be tested immediately after the function call: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-47 MBBSEXEC Advanced Features -Writing/calling your own functions . . call(func1) if(@resultcode == 0) { . . } else { . . } . . NOTE: The RETURN command is to be used only within a function. IMPORTANT: The GOTO() statement, if used within a function, is to be used ONLY to branch to a label contained within that function!! NOTE: You can improve performance (ie: speed) of the processing of your .MEX files by using function declarations and function calls. For exmaple, the following code: if(expression) { . . . . } will run slower than: if(expression) { call(funca) } where "funca" would contain the same code as is between the braces of the "if(expression)" statement above. This is especially true when large numbers of statements appear between the brackets of the if() statement. To clarify this further, the speed improvement comes about when the if(expression) statement evaluates to "false". Because MBBSEXEC is an interpreter, it must read (and ignore) every line of code after the if() statement until it finds its matching brace. However, with the call() statement, it's only one statement which is read (and ignored) in the case of the if() statement evaluating to "false". MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-48 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features -Setting the NEXT record to Process The function SETREC(x) sets the next record number to get. The function only "sets" the next record but doesn't actually retrieve it until the #STOP statement is encountered, which forces the read of the next record and executes the code at the #START statement again. The 'x' portion can be either a hard-coded number or a @TALLYx variable. Here's an example of how SETREC(x) might be used: #START if(@tally0 == 0) { clog("Record Range: 0 to ",@hirec) goto(skip_firstime) } clog("ID: /",@id," Name: ",@firstname," ",@middlename," ",@lastname) skip_firstime: @tally0 = 1 input("Record number to fetch => ",@tally1) setrec(@tally1) #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-49 MBBSEXEC Advanced Features - Executing an External Program You can run an external program by using the SYTEM() call: system("pgmname.exe parm1 parm2") The above example calls PGMNAME.EXE, passing it two arguments: PARM1 and PARM2. The argument to the SYSTEM() command can be within a quoted string, or can be a @STRINGx variable: @string1 = "pgmname.exe parm1 parm2" system(@string1) The parameter to the SYSTEM() call MUST include the full program name including the .exe extension. If it is not in the current directory, you should include the complete filespec (drive,path,filename and extension: "C:\MAGNUM\EXT_DIR\PKUNZIP2.EXE"). NOTE: The SYSTEM() command sets the @RESULTCODE (a read-only variable). If you wish to obtain the resultcode, it should be checked immediately following the SYSTEM() call: system("pgmname.exe parm1 parm2") if(@resultcode == 1) { exit(1) } If the program cannot be found or started, the @RESULTCODE variable will be set to -1. Otherwise, it will be set to the value the called program sets at termination. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-50 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data Your .MEX program can save its data (@TALLYx and @STRINGx) with the SAVE_DATA(filename) command. This command saves the values of all @TALLYx and @STRINGx variables to the file specified by 'filename'. The 'filename' paramater can be a quoted string or a @STRINGx variable. Valid Examples: SAVE_DATA("e:\mex1data.var") or SAVE_DATA(@STRING5) Once a datafile is saved, it may no longer be needed when your program finishes. For this reason, we've added the command DELETE(filename), which can have the format: DELETE("e:\mex1data.var") or DELETE(@STRING5) Your .MEX program can restore the data (@TALLYx and STRINGx) previously saved with the SAVE_DATA(filename) command by using the command RESTORE_DATA(filename). The 'filename' parameter can be a quoted string or a @STRINGx variable. Valid Examples: RESTORE_DATA("e:\mex1data.var") or RESTORE_DATA(@STRING5) As before, when starting out the MBBSEXEC.EXE program, you can optionally place a userid on the command line after the filename: MBBSEXEC filename[.mex] [userid] Now, the syntax is: MBBSEXEC filename[.mex] [userid] [@datafile] If you plan on using the [userid] parameter, it must be the first paramater after the "filename[.mex]" parameter. The [@datafile] parameter gives the filespec of the datafile to be loaded (values of @TALLYx and @STRINGx variables) at program startup. The @ symbol preceeding the filename is not part of the filename, but merely an indication to the MBBSEXEC.EXE program that a datafile follows. Examples: MBBSEXEC LEVEL20 1 @MEXDATA1.VAR MBBSEXEC REPORT @MEXDATA2.VAR The datafile is an ASCII text file, whose format is: @TALLY0 = 15 @TALLY1 = 3421 . . @TALLYn = 0 . . @STRING0 = "This is string 0" @STRING1 = "String 1" MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-51 MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data . . @STRINGn = "String n" You need only specify the variables you wish to be initialized with the data you provide. This file is in the same format as the "filename" specified by the SAVE_DATA("filename") and RESTORE_DATA("filename") commands, and can also subsequently be used at runtime by the RESTORE_DATA("filename") command. The SAVE_DATA() command can take a null parameter. For example, the command SAVE_DATA("") will save the data to the file from which the MBBSEXEC.EXE program was started with if the @datafile parameter was used at startup. In other words, if MBBSEXEC was started with: MBBSEXEC @mexvars.tmp then the SAVE_DATA("") command will is equivalent to issuing the command: SAVE_DATA("mexvars.tmp") Likewise, the command RESTORE_DATA("") is equivalent to: RESTORE_DATA("mexvars.tmp") Utilizing the SAVE_DATA(), RESTORE_DATA(), and SYSTEM() commands, it's possible to cross-reference between databases. For example, if you wish to Process the FILE database, but want the name of the person who uploaded the file, the .MEX file processing the FILE database would look something like the following: @tally1 = @who save_data("findout.tmp") system("e:\magnum\pgm_dir\mbbsexec.exe findul @findout.tmp") restore_data("findout.tmp") clog("File ",@name, "was uploaded by ",@string1) and the .MEX file called would process the USER database as follows: if(@thisrec == @lorec) { setrec(@tally1) } else { slog(1,@firstname," ",@middlename," ",@lastname) save_data("") exit(2) } The data saved by the SAVE_DATA() command can be read by MSESSION with the MILC command @&x which causes the saved values of @TALLYx and @STRINGx variables to be read/mapped into MSESSION's @Nx an @Zx variables. The RESTORE_DATA() command can read a data file stored with MSESSION's MILC command @$x which will read/map MSESSION's @Nx and @Zx MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-52 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features-Save/Restore/Start/Delete Pgm Data variables to MBBSEXEC's @TALLYx and @STRINGx variables. This feature of reading/saving/mapping MSESSION and MBBSEXEC data allows the two programs to communicate and provides for an ideal way of passing information to/from MBBSEXEC if MSESSION calls MBBSEXEC as a child process (door). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-53 MBBSEXEC Advanced Features - Sample .MEX Programs The following demonstrates a practical use for a .MEX program which searches your USER database based on a lastname which it prompts you for: #CONFIG_FILE: E:\MAGNUM\PGM_DIR\MBBSINIT.1 #LOG_FILE: stdout #DATABASE: USER #START if(@thisrec == @lorec) { input("Lastname to Search For => ",@string1) } ! ! log("Comparing ",@\34,@lastname,@\34," and ",@\34,@string1,@\34) ! if(@lastname == @string1) { log("Name: ",@lastname,", ",@firstname," ",@middlename) log(" ID: /",@id) log("From: ",@city," ",@state," - ",@country) log("Last Called on ",@lastcall) log("- - - - - - - - - - - - - - -") input("Search for Next Occurence (Y/N) => ",@string2) if(@string2 == "N") { exit(5) } } #STOP The following demonstrates a sample .MEX programs which utilize most of the techniques covered in the advanced section. The purpose is to provide a sample of how these functions might be put together: ! ! Sample .MEX program to provide numbers of how many users are in ! each security level (you need to change the @level statements to ! match your particular system). ! #CONFIG_FILE: e:\magnum\pgm_dir\mbbsinit.1 #LOG_FILE: FIND.LOG #DATABASE: USER #START ! ! Equate our names with MBBSEXEC names for readability ! MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-54 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC Advanced Features - Sample .MEX Programs equate : level5 = @tally1 equate : level6 = @tally2 equate : level10 = @tally3 ! Used for level 10 tally equate : level15 = @tally4 equate : level20 = @tally5 equate : level30 = @tally6 equate : over_level_30 = @tally7 equate : active_users = @tally8 equate : deleted_users = @tally9 equate : total_users = @tally10 ! ! ---------- DETERMINE - function to determine user level ! fstart:determine ! function to determine user level if(@level == 5) { ! check for level 5 level5 = level5 + 1 ! increment if true } else { ! otherwise if(@level == 6) { ! check for level 6 level6 = level6 + 1 } else { if(@level == 10) { level10 = level10 + 1 } else { if(@level == 15) { level15 = level15 + 1 } else { if(@level == 20) { level20 = level20 + 1 } else { if(@level == 30) { level30 = level30 + 1 } else { if(@level > 30) { over_level_30 = over_level_30 + 1 } fstop:determine ! end procedure ! ! ------- FINISHUP - function to report results - called at last record ! fstart:finishup clog(@\13@\10) clog("Level 5 Users: ",level5) ! log level5 users clog("Level 6 Users: ",level6) clog("Level 10 Users: ",level10) clog("Level 15 Users: ",level15) clog("Level 20 Users: ",level20) clog("Level 30 Users: ",level30) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-55 MBBSEXEC Advanced Features - Sample .MEX Programs clog("Users >Level30: ",over_level_30) clog("- - - - -") clog(" Active Users: ",active_users) clog("Deleted Users: ",deleted_users) clog(" Total Users: ",total_users) log("Level 5 Users: ",level5) log("Level 6 Users: ",level6) log("Level 10 Users: ",level10) log("Level 15 Users: ",level15) log("Level 20 Users: ",level20) log("Level 30 Users: ",level30) log("Users >Level30: ",over_level_30) log("- - - - -") log("Active Users: ",active_users) log("Deleted Users: ",deleted_users) log(" Total Users: ",total_users) fstop:finishup ! ! --------- Main Processing (Main Program Body) -------- ! total_users = total_users + 1 if(@deleted == FALSE) { call(determine) active_users = active_users + 1 } else { deleted_users = deleted_users + 1 } if(@thisrec == @hirec) { call(finishup) exit(5) ! exit the program with return code of 5 } #STOP MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-56 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) If you've completed this chapter from start to finish, then you have a fairly good grasp of the endless capabilities of the MBBSEXEC program and its power. Because MBBSEXEC gets its input from STDIN, and writes its output to STDOUT and/or STDERR, it can also be run as a child process (door) under the BBS. This gives added functionality to the program. The remainder of this chapter summarizes the MBBSEXEC commands. General Rules - The .MEX file must be an ASCII text file, created with a text editor which ends every text line with a CR/LF pair. - No text line may exceed 120 characters. - No .MEX file can exceed 64,000 bytes (filesize). - Maximums: up to 500 Labels up to 200 brace levels up to 100 function declarations up to 100 function call nesting (ie: similar to a stack) - Each { must have a matching } and vice versa. - GOTO restrictions: - If used within a function, the label (target) must be within that function. - If used outside of a function, the label (target) should appear within the same set of braces. - Branching to a label in the main program body (brace level 0) is acceptable anywhere except from within a function. All .MEX programs start with: #CONFIG_FILE: Full filespec to MBBSINIT.x #LOG_FILE: Filespec or devicename to write to (ie: PRN) #DATABASE: One of USER, FILE, MSG, RJE, UTILIZ #START and end with: #STOP The filename given in the #LOG_FILE statement is where all log() or blog() statements are written to. If ",A" (without the quotes) follows the filename, the log file is appended to. If you plan on using only blog() statements and wish to append to the file, use ",U" (without quotes) after the filename instead. If the filename is STDOUT, then output will be routed to the standard output device (console) and this name should NOT be followed by ",A" or ",U". If processing the USER database, a record number can optionally follow the #START statement. This will cause MBBSEXEC to process only that record number, then terminate the program. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-57 MBBSEXEC -- Program Summary (All Sections) All .MEX executable program statements must appear between the #START and #STOP program directives. All .MEX executable program statements NOT appearing between { and } (beginning and ending braces) or between FSTART and FSTOP are considered to be part of the MAIN PROGRAM BODY. If a syntax or other error occurs while processing your .MEX file where MBBSEXEC issues a line number referencing the error, MBBSEXEC creates a numbered file with an extension of .SNP (snapshot) - the line number in which the error occurred will refer to the line number of the .SNP file. For example, if your program is UPDATE.MEX and MBBSEXEC terminates due to an error on line 45, the MBBSEXEC creates a numbered file called UPDATE.SNP - line 45 of UPDATE.SNP is where the error occurred. IF() statements and WHILE() statements are of the format: IF(expression) { . . } and WHILE(expression) { . . } The opening brace ( { ) MUST appear on the same text line as the IF() or WHILE() statement itself. The (expression) part of the IF() or WHILE() statement MUST compare two values, separated by one of 7 available comparators: == test for equality >= test for greater than or equal to <= test for less than or equal to != test for not inequality > test for greater than < test for less than ~ test for string2 within string1 (strings only) The format of an ELSE statement is: } ELSE { or ELSE if using braces, they must appear all on the same line as the actual ELSE statement. Every ELSE statement MUST have a matching IF() statement. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-58 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) All { and } pairs must match up (there should be the same number of { braces as } braces). Nesting ( { and } within other { and } ) must not exceed 200 levels of depth. The MAIN PROGRAM BODY is considered to be level 0. ALL DATES are stored in US date format (MM/DD/YYYY) and must always be 10 characters in length. All STRING comparisons against dates must be in US date format and must always be 10 characters in length. All date string assignments must be in US date format and must always be 10 characters in length. The exclamation mark (!) denotes a comment. Comments are ignored by MBBSEXEC (stripped out internally). A comment ends when the physical text line holding the '!' character ends. The exclamation mark (!) is NOT treated as a comment when: - It is immediately followed by an equal sign (!=). - It is enclosed within double quotes ("..!.."). - It is immediately preceeded and followed by the single quote character ('!'). You can EQUATE (substitute) your own variable names for any @TALLYx or @STRINGx variable. You must EQUATE the name before you can use it. The format of an EQUATE statement (via examples) are: EQUATE : MY_NAME = @STRING15 EQUATE : TTL_CALLS = @TALLY9 The names you use in your EQUATEs must not exceed 30 characters, and must not contain any characters other than numeric (0-9), alpha (A-Z), and the '_', '.' and '@' characters. The first character of the name must be alpha. You can write your own functions by beginning your function with FSTART:funcname and ending with FSTOP:funcname. Example: FSTART:print_summary . . . FSTOP:print_summary Program statements appearing within FSTART and FSTOP are never executed unless explicitly called with the CALL(funcname) parameter. Functions CALL(funcname) - Calls a function declared with FSTART/FSTOP. If the called function issues a RETURN(x) statement, the value of @RESULTCODE is set and should be checked immediately after the call if you wish to obtain the value: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-59 MBBSEXEC -- Program Summary (All Sections) CALL(print_summary) IF(@resultcode != 0) { . } BLOG() - Logs (writes) a fixed length record to the #LOG_FILE file. FORMAT: BLOG(length,parm1[,...parmn]) where 'length' indicates how many bytes to write. If the total is longer than 'length', it is truncated to 'length'. If shorter than 'length', it is padded with nulls (binary zeros). CLOG() - Logs (displays) to the console (via STDERR). FORMAT: CLOG(parm1[,...parmn]) LOG() - Logs (writes) a variable length record to the #LOG_FILE file. FORMAT: LOG(parm1[,...parmn]) SLOG() - Logs (writes) a variable length record to a @STRINGx variable. FORMAT: LOG(x,parm1[,...parmn]) where 'x' indicates which @STRINGx variable to write to. IF() { - Covered above under 'General Rules'. } ELSE { - Covered above under 'General Rules'. WHILE() { - Covered above under 'General Rules'. GOTO(label) - Branch to 'label'. 'label' may appear anywhere in the file and must not exceed 30 characters. If branching to 'label' from within nested { and } pairs, or branching to 'label' to within a different { and } pair, the results will be unpredictable. General rules are: Branch to level 0 from anywahere is always acceptable unless the GOTO is issued from within a function (within FSTART and FSTOP statements). Branch from level 0 or from within a { and } pair to a different { and } pair has unpredictable results! LABEL: - Identifies the target of a GOTO statement. LABEL must not exceed 30 characters and must be followed by a colon (:). Up to 500 labels are allowed per .MEX file. EXIT(resultcode) - Causes MBBSEXEC.EXE to end, returning control to the calling program (or .CMD file). 'resultcode' is the exit code the program will end with (can be checked against the ERRORLEVEL command if in a .CMD file). resultcode should range from 2 to 255. Although a resultcode of 0 or 1 is acceptible, MBBSEXEC.EXE normally ends with a 0 or 1 anyway and thus, codes of 0 or 1 should be avoided. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-60 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) INPUT("input text",@STRINGx) - Displays "input text" and prompts the user to enter something. User input is stored in variable @STRINGx. Input is obtained via STDIN, and can thus be redirected if desired. INPUT("input text",@TALLYx) - Displays "input text" and prompts the user to enter something. User input is stored in variable @TALLYx. Input is obtained via STDIN, and can thus be redirected if desired. If an invalid number is entered (ie: non-digits), the result in @TALLYx will be 0 (zero). RETURN(x) - For function use only. Terminates a currently-executing function. Sets the value of @RESULTCODE to value 'x'. 'x' can be numeric digits or a @TALLYx variable. The alternate form of of RETURN(x) is simply RETURN wihout parens which simply terminates the currently-executing function but leaves the @RESULTCODE unaltered. SYSTEM("pgmname.exe parms") - Executes an external program. The parameter can be a quoted string or a @STRINGx variable containing the information. The @RESULTCODE variable is set after the external program finishes and should be checked immediately after the SYSTEM() call if you wish to obtain the result: SYSTEM(@STRING1) IF(@RESULTCODE > 0) { . } The @RESULTCODE will be -1 if the program could not be run (or found). SETREC(x) - Sets the record number of the NEXT record to read (will be read/processed when the #STOP statement is found). 'x' can be a number or a @TALLYx variable. The value of 'x' must fall within 0 and the value of @HIREC. SAVE_DATA("filename") - Saves the values of the 100 @TALLYx and 100 @STRINGx variables to "filename". "filename" can be in quoted strings or in a @STRINGx variable. RESTORE_DATA("filename") - Restores the values of the @TALLYx and @STRINGx variables from "filename". "filename" can be in quoted strings or in a @STRINGx variable. DELETE("filename") - Deletes "filename" from disk. Filename can be in MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems The MBBSEXEC Sysop Maintenance Utility Program Page 9-61 MBBSEXEC -- Program Summary (All Sections) quoted strings or in a @STRINGx variable. If a complete filespec (drive,path,filname.ext) is not given, the current directory will be assumed. SNAP("filename") - Writes a snapshot of your .MEX program statements to "filename". READ-ONLY VARIABLES: @TODAY - Holds current date. @THISREC - Holds current record number. @LOREC - Holds lowest record number - Always 0. @HIREC - Holds highest record number. @RESULTCODE - Holds result of LAST call to RETURN(x) or SYSTEM(filename) USER (PROGRAMMER) VARIABLES: @TALLYx - Holds numeric data. There are 100 tally variables available named @TALLY0 to @TALLY99. @STRINGx - Holds string data. There are 100 string variables available named @STRING0 to @STRING99. @TALLY[x] - Indirectly addresses a tally variable. The tally variable being indirectly addressed is based on the value of @TALLYx. @STRING[x] -Indirectly addresses a string variable. The string variable being indirectly addressed is based on the value of @TALLYx. For both @STRING[x] and @TALLY[x] indirect addressing, the [x] portion can use pre-increment or post-increment ([+x] or [x+]). It can also use pre-decrement or post-decrement ([-x] or [x-]). Optionally, a combination of pre/post-increment/decrement can be used ([+x+] or [-x-] or [+x-] or [-x+]). Refer to section on "Indirect Addressing" for more information. You may use the word @INDEX in place of @TALLY (they are interchangeable and refer to the same thing). @INDEX is internally converted to @TALLY by MBBSEXEC. SPECIAL FIELDS IN USER DATABASE The following fields of the USER database are "special": @FILE_U_AREAS @FILE_D_AREAS @FILE_L_AREAS @MSG_R_AREAS @MSG_W_AREAS @MSG_L_AREAS @CONFERENCES @FREE_DL_AREAS @DISP_CMDS These fields hold up to 26 areas (A-Z) each. Rather than assigning to these fields (overwriting what's already there), you can optionally append or delete areas from these fields. Example: @FILE_D_AREAS = "+IM" adds I and M as areas to @FILE_D_AREAS MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 9-62 The MBBSEXEC Sysop Maintenance Utility Program MBBSEXEC -- Program Summary (All Sections) @MSG_R_AREAS = "-SK" deletes S and K as areas to @MSG_R_AREAS --- STARTING MBBSEXEC: MBBSEXEC filename[.mex] [userid] [@datafile] If you plan on using the [userid] parameter, it must be the first paramater after the "filename[.mex]" parameter and must consist of only digits. The [@datafile] parameter gives the filespec of the datafile to be loaded (values of @TALLYx and @STRINGx variables) at program startup. The @ symbol preceeding the filename is not part of the filename, but merely an indication to the MBBSEXEC.EXE program that a datafile follows. Examples: MBBSEXEC filename MBBSEXEC filename 320 MBBSEXEC filename @mexdata.var MBBSEXEC filename 320 @mexdata.var MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum Utility Programs Page 10-1 STOPMBBS.EXE, STOPRJE.EXE and KILLPROC.EXE All three utility programs are located in your PROGRAM DIRectory. The Magnum utility programs STOPMBBS.EXE and STOPRJE.EXE are mainly for those users of Magnum on LAN systems. However, you may benefit from the use of these programs even if you're running a single-node BBS on a single computer. STOPMBBS.EXE CAUTION: This program will cause instant termination of ALL sessions, on ALL machines attached to your LAN and without warning to online users! The intent of this program is to keep users offline while a new version of the software is being installed or vast changes are being made by the Sysop. For Instructions on program use, execute STOPMBBS.EXE without parms. It is advisable that ONLY the system administrator (for LAN users of Magnum) have a copy of this program. STOPRJE.EXE Because the RJEMONIT.EXE program is a daemon process, there's no way to stop it (once its started) short of a system reboot. The STOPRJE.EXE utility program, however, will terminate actively running RJEMONIT.EXE programs on ALL machines. For Instructions on program use, execute STOPRJE.EXE without parms. It is advisable that ONLY the system administrator (for LAN users of Magnum) have a copy of this program. KILLPROC.EXE Magnum calls this program internally, but you can benefit from this program for killing other programs on your system if you know their PID (Process Identification Numbers). For Instructions on program use, execute KILLPROC.EXE without parms. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank Supplied External and RJE Programs with Magnum BBS Page 11-1 Supplied External (child or 'door') programs Included with your Magnum BBS package is UTILIZ.EXE -an external program providing useful utilization charts of your system. The program can be invoked from the "[D]oor" (child) selection from the main menu. Usage of the program is self-explanatory. This program uses information in the UTILIZ.DAT database in your SESSION directory. This database exists if the TRACK_UTILIZATION parm in your STARTUP.x file(s) is set to Y. Supplied RJE programs Also included with your Magnum BBS package are RJE programs for POWER (Personal Offline Writer Editor Reader) processing. These can be invoked from the RJE menu's "[L]list/Execute" command. Because RJE processes run detached in the background, the remote user is free to perform any other BBS function(s) or to log off - the RJE processes will continue to run until completed. POWER processing allows the remote user to create a file of messages on the system which they can later download for offline viewing. When the user has a copy of the POWER.EXE program at their end, they can view, respond to, and create messages offline at their leisure. The next time the remote user logs on, they can upload their responses to the RJE facility for processing. The setup which we've supplied includes 2 RJE utilities: 1) MSGLIST.EXE - This program (in conjunction with the ADDRJE.EXE program) creates a compressed file which the user can download, containing all messages on the system of the user's choice (date range & msg areas). At this time, messages from other Magnum systems are not supported by this program. 2) RJEPOW.EXE - This program (in conjunction with the GETPOW.EXE program) allows the remote user to upload pre- prepared messages (via the POWER.EXE utility pgm to your system. The RJEPOW.EXE program processes these messages in the background and places them in the appropriate message areas on the BBS. Again, both can be invoked from the RJE menu's "[L]ist/Execute" command. For both of the above, your remote users will need a copy of the offline POWER (Personal Offline Writer Editor Reader) program. This program is includes POWER.EXE (DOS) and POWER2.EXE (OS/2) for whichever OS your users are running on when they decide to use offline POWER processing. The file POWER3.ZIP is for your remote users to download and use. This is on your distribution diskette as A:\MAGNUM\RJE_DIR\POWER3.ZIP and should be 'uploaded' to your file database if you plan on allowing your users to use this program. Complete documentation on its use is in the the .DOC file contained within POWER3.ZIP. You might find it beneficial to review the files CHILDREN.BBS (called when [D]oor is invoked from main menu), and RJELIST.BBS (called when [L]ist/Execute is invoked from the RJE menu). These files provide examples of how we've used MILC commands to produce the resultant interaction between user, BBS and external programs. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank The NotePad Facility Page 12-1 Magnum incorporates a NotePad facility. Although not obvious from the menus, you may want to inform your users about it via one of the HELLOx.BBS files or via a message in an external menu. The NotePad serves a variety of purposes for you and your users: The NotePad as a "NotePad" To use the NotePad as merely a "NotePad" (ie: to make notes to yourself), simply press <Ctrl-O> (press O while holding down the Ctrl key). You'll be prompted as to which note # you wish to create or modify (0-99). Up to 100 NotePads are allowed for each user of your BBS. If any NotePads already exist for the user, they'll be displayed (numbered) along with their titles so that the user can pick which NotePad to read or modify. If this is the user's first time depressing <Ctrl-O>, s/he can create a note simply by picking a NotePad number (0-99). In any case, Magnum will take the user into the ANSI message editor and the user can read and/or modify the NotePad. The same ANSI editor is used for creating NotePads as is used for creating messages. The NotePad as a "Cut & Paste" Tool for Messages When responding to or reading a message, you can save the contents of that message into a NotePad by [R]eplying to that Message with the ANSI editor. Once inside the ANSI editor, choose <ESC><ESC> (hit the ESC key twice in succession). An options menu will appear. To save the message (or any portion of) the message you're replying to, choose 'ReRead Original Message w/ Marking Facilities'. Mark the lines of the original message that you're interested in and bring those lines into YOUR response. Choose <ESC><ESC> again and choose 'NotePad Facilities' from the options menu and 'save' your reply (which now contains portions of the original message) into your personal NotePad. When creating a message, you can also bring in text lines from any of your NotePads into your message. Choose <ESC><ESC> and then 'NotePad Facilities'. Follow the appropriate prompts to proceed. The NotePad as a List of User ID's for CC's (Carbon Copies) When entering a NEW message, you can provide ID numbers of users to issue CC's (Carbon Copies) of your message to when you save your message. If you'll be routinely sending CC's to a specific group of users, you can have one (or more) of your NotePads contain a list of those User ID's. When prompted for the ID number of a user to be the recipient of a CC, simply provide the NotePad number instead. Magnum will then use that NotePad to read and process the ID numbers of the users to send CC's to. To have a NotePad contain User ID's, simply create a NotePad (any NotePad number will do), and provide the ID numbers as follows (via example): /10 /55 /203 /44 /8 Note that the CC list is free-form, meaning that you're not limited to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 12-2 The NotePad Facility one user id per text line. The CC list can be used when, after entering a new message, the CC prompt will ask for who to send the CC to as usual. Instead of replying with /id as in the past (which is still supported), you can repond with #5 (note the #) to signify to use the CC list contained in note #5. After CC's have been processed from note #5, the prompt will re-appear so that you might enter additional CC's (or note #'s with CC lists). If you're using the remote mail facility, the NotePad can also hold CC lists containing remote addresses! Unlike normal recipients (as many of the /ID entries per text line as you wish), a remote user entry is one per line. An example CC list ala a notepad might look like: /10 /55 /32 $1989070000/0 $1989110006/195 /34 /404 The above would generate CC's to ID 10, 55, 32, 34 and 404 on your BBS. It would also generate CC's to the Sysop (/0) of the Magnum system having a serial# of 1989070000 and to ID /195 of the Magnum system having a serial# of 1989110006. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Setting up Additional Copies of Magnum on your LAN Page 13-1 If this is a 2nd (or 3rd, etc) copy of Magnum BBS that you've purchased to allow for additional incoming dialup or 'pipe' lines (requires optional 'pipe' module), you'll need to install this additional copy on a workstation (or server) other than the one your original Magnum BBS is running on. This chapter describes how to set up your additional, serialized copy or copies of Magnum BBS on other workstations and be able to share the databases and files with your original Magnum BBS. If you purchased this additional copy of Magnum and do NOT wish to share the databases and files with your original Magnum BBS, then disregard this chapter. For starters, you'll need to make sure that you supply the serial number of your ORIGINAL Magnum BBS (from your 1st system) in ALL of your STARTUP.x file(s) for this additional copy by specifying that serial number in the PARENT_SERNUM parameter of your STARTUP.x file(s). If you do not supply the same serial number as that of your ORIGINAL Magnum BBS diskette (not that of your new copy of Magnum), then you will not be able to share the databases and damage may occur to your original databases. In addition to setting up the same serial number as that of your ORIGINAL (first) Magnum BBS system, you'll need to set up the workstation that you'll be installing the additional copy of Magnum on to be able to share (have READ/WRITE access) to ALL subdirectories specified in your STARTUP.x file(s) for your original Magnum System. For each STARTUP.* file which exists, bring the file into your favorite text editor and modify the following such that it points to the subdirectories matching that of the server: PROGRAM_DIR: *** (Cannot be shared! Must be unique to add'l copy) SESSION_DIR: BULLETIN_DIR: MENU_DIR: HELP_DIR: DISPLAY_DIR: EXTERNAL_DIR: RJE_DIR: MSG_DIR: WORK_DIR: *** (Cannot be shared! Must be unique for EVERY node) USERS_DIR: SYSOUT_DIR: *** (Cannot be shared! Must be unique to addl' copy) ; ; ------ File Directories ; FILEDIR_A: FILEDIR_B: FILEDIR_C: FILEDIR_D: FILEDIR_E: FILEDIR_F: FILEDIR_G: FILEDIR_H: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 13-2 Setting up Additional Copies of Magnum on your LAN FILEDIR_I: FILEDIR_J: FILEDIR_K: FILEDIR_L: FILEDIR_M: FILEDIR_N: FILEDIR_O: FILEDIR_P: FILEDIR_Q: FILEDIR_R: FILEDIR_S: FILEDIR_T: FILEDIR_U: FILEDIR_V: FILEDIR_W: FILEDIR_X: FILEDIR_Y: FILEDIR_Z: For example, if the Server (original Magnum installation) designates its SESSION_DIR as: E:\MAGNUM\SES_DIR then your workstation's path (additional copy of Magnum) might look something like: S:\MAGNUM\SES_DIR or whatever letter on your server is designated to match the same drive letter that the server uses to house the session directory. The PROGRAM_DIR, WORK_DIR, and SYSOUT_DIR must NOT use the same directories as designated by the server or any other workstation. EACH WORKSTATION MUST HAVE ITS OWN, UNIQUE PROGRAM_DIR, WORK_DIR and SYSOUT_DIR directory names! You may have to manually create these subdirectories on your workstation as well as supply those same names as pathnames for their respective keywords in your STARTUP.* files. The PROGRAM_DIR is the directory where you've installed (or plan to install your additional copy of Magnum). Note that ALL BBS functions are supported (as in your original Magnum) with the exception of Group Chat. Chat is currently limited to those logged onto the same machine (being defined as the machine in which the MBBS.EXE program is running on). In other words, if you have the 9-node version (for example) on your Server, and the 9-node version on your workstation, only the 9-nodes of each machine can be used for Chat within the same group of 9-nodes. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Setting up Additional Copies of Magnum on your LAN Page 13-3 Remapping Directories for your Workstation Remapping of directories is recommended. Unless you're running on a LAN, remapping of directories will be of little to no use to you. To perform remapping of directories, create a file (node specific) in the PROGRAM DIRectory of your workstation called REMAPDIR.x (where 'x' is the node#). The format of this ASCII text file is: oldpath = newpath Wherever 'oldpath' is found, it will be replaced with 'newpath'. Example: D:\MAGNUM\ATM = M:\FONT\ATM D:\MAGNUM\ANNOUNCE = X:\BBS\NOTICES Using the above, a filename of d:\magnum\announce\meeting.txt would become x:\bbs\notices\meeting.txt - the actual filename.ext doesn't change, only the directory path housing that filename.ext changes. Server / netnames are also allowed. For example, the following statement is also valid: D:\MAGNUM\ATM = \\SERVER1\DRIVEX\FONTS\ATM Note that both 'oldpath' and 'newpath' are limited to a maximum of 65 characters each. You may have as many text lines as you wish in this file. NOTE: The intention of remapping is NOT to provide a 'quick & dirty' override to the directory path names you defined in your STARTUP.x file(s), but to override any hard-coded directory names in your displayable files! For example, files which "include" other files (with MILC @Ix command) would only work properly on the server machine (on a network). Although the remapping function DOES provide a 'quick & dirty' override to the directory path names defined in your STARTUP.x file(s), we advise extreme caution when doing so. You should NEVER remap the SESSION or PROGRAM directories! In addtion to MSESSION.EXE, the following programs also observe remapping: MBBSEXEC, MSGLIST, RJEPOW. REMAPDIR.x must be in the PROGRAM DIRectory of each workstation, and must remap to the proper places in order for the 'extended msgbase' and 'extended filebase' optional modules to work properly. Also, remapping is required for the 'compressed message list' function of the RJE menu to work. Note that MBBS.EXE and all other .EXE's not listed in the above paragraph do NOT observe remapping. Once again, if you're not running a LAN, re-mapping will be of little to no use to you. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank For Systems using 'Extended File' and/or 'Extended MsgBase' Page 14-1 The 'user' fields FILEBASE and MSGBASE indicate the LAST FileBase and MsgBase the user was in. The next time the user logs on, Magnum will automatically change to these bases. The fields FILEGRP and MSGGRP in every user's records add even more flexibility to the extended MsgBase and extended FileBase modules. Until now, access to certain File and Msg Bases were determined solely by security level. With the FILEGRP and MSGGRP fields, each user can be assigned to a File Group or Msg Group (think of these groups as profiles). By way of example, let's suppose that you set up John Doe (ID: /10) such that his FILEGRP is 3 (you can do this by pulling up record 10 of the User database area of the Sysop menu when logged on as Sysop and changing his FILEGRP to 3; or you can write a .MEX program to perform bulk updates). Regardless, assuming that John Doe (ID: /10) is assigned to FileGrp 3. This means that Magnum will look in your SESSION DIRectory for a file by the name of FILE3.GRP and if it finds it, the contents of this ASCII text file will override the security levels imposed by the FILEBASE.EXE program when you set up your FileBases. If Magnum doesn't find FILE3.GRP, Magnum will act as it did prior to this version: it determines access to the different FileBases by means of security levels set by the FILEBASE.EXE program. Assuming that the file FILE3.GRP exists, the contents might look like the following: ; ; Definitions file for File Group 3 ; ; Users assigned to File Group 3 have access to these File Bases ; regardless of Security Level. ; 1 RWL ; Los Angeles OS/2 User Group.. Override Read/Write/List Access 2 RL ; OS/2 2.0.......................... Override Read/List Access 38 L ; California Real Estate............ Override List Access 224 ; New York Real Estate............... No Override As you may have guessed from the above sample file, the semicolon (;) denotes the beginning of a comment. A comment starts with a semicolon and lasts until the end of that text line. Blank lines are ignored. The above sample allows all users who's FILEGRP field is set to 3 to have access to FileBases 1, 2, 38 and 224. The comments (ie: New York Real Estate) are merely comments and may or may not have anything to do with the content of the actual FileBase denoted by that number. If R appears, READ (or download) access will be given to this FileBase regardless of the READ security level set with the FILEBASE.EXE program. If W appears, WRITE (or upload) access will be given to this FileBase regardless of the WRITE security level set with the FILEBASE.EXE program. If L appears, LIST access will be given to this FileBase regardless of the LIST security level set with the FILEBASE.EXE program. Likewise, the MSGGRP field works in an identical fashion except that it expects to find its information in MSG3.GRP if 3 were assigned to the MSGGRP field of a particular user. NOTE1: The FILEGRP and MSGGRP fields override the ability to ACCESS MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 14-2 For Systems using 'Extended File' and/or 'Extended MsgBase' FileBases and MsgBases which the user would not ordinarily have access to. Furthermore, the .GRP file containing the definitions of a group, can override READ(download), WRITE(upload) and LIST security levels. Note that if a dependency on MEMODATE1 or MEMODATE2 exists within a particular FileBase (as set by FILEBASE.EXE), these parameters will override it! NOTE2: Although you don't need to use groups at all, the use of such groups will definitely demonstrate a speed increase in the presentation of the different FileBases and MsgBases for the user to choose from. NOTE3: For those Sysops running the type of board where each user represents a different company for example, they might want to set up their BBS such that these users only have access to one particular FileBase and one particular MsgBase. Let's suppose that users of XYZ Corp are assigned FileBase 5 and MsgBase 8. The Sysop could then assign 5 to their FILEBASE and 8 to their MSGBASE. Furthermore, the Sysop could disable the "[F]ileBase Change" and "[M]sgBase Change" menu selections by raising the security level of these menu choices to one higher than these users. This, in effect, insures that users of XYZ Corp will only see (and know about) FileBase 5 and MsgBase 8. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-1 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) ------------------------------------------- AMMO (Automated Magnum Mailer Option) is built into Magnum systems and allows the Sysop the option of implementing this capability. The term AMMO refers to the link level layer of Magnum systems, while the term RMAIL refers to the user level layer. When we speak of AMMO in this chapter, it will be about setting up and using this option from the Sysop's point of view. When we speak of RMAIL in this document, it will be about using the 'remote mail' facility of Magnum from your caller's point of view. Introduction: ------------- As Sysops, we're all familiar with the callers (users) of your BBS dialing in with their modems (or pipe modules), going to the message section, and reading their mail, responding to their mail, and entering new mail. It's very similar to inter-office mail at a company. With the introduction of RMAIL (remote mail), the callers (users) of your BBS can now do the same thing but are no longer limited to the users of your BBS. They can exchange messages with remote users of remote Magnum BBS systems! The same features that exist currently (receipts, CC's, message forwarding, private mail, public mail, messages to ALL) also exist with RMAIL. Just like mailing a letter via the postal service, the user needs to know the address of someone on a remote system. The address is composed of 2 things: the remote system's serial number, and the remote user's ID number on that system. An RMAIL address looks like the following: $1989070000/0 The $ character specifices that this is RMAIL (not local mail). The 1989070000 number happens to be the serial number of the Gilmore Systems BBS located in Thousand Oaks, California. The /0 is the user id of the Sysop at that system. In this case, the Sysop is Chuck Gilmore. So the above address is actually the address of Chuck Gilmore at his Thousand Oaks BBS. Envision that each Magnum System is like a city itself. When you send a letter to someone through postal services (mail), you include the person's name and address on the envelope, along with your name and return address. In the above example, the Magnum Serial# is the equivalent of the "city, state, zip and country" on the envelope, and the ID of the user on that system you're sending mail to is the person's "name". Together, the serial# and name form a complete address. Suppose you want to send a letter to "John Smith" in Chicago. Knowing that John smith is ID /348 on the Chicago BBS, his complete address would be $1991000002/348 ($ specifies RMAIL followed by the 10-digit serial#, the / character and ID). The advantages of using RMAIL as opposed to postal mail is multi-fold: - You don't need to know city, state, zip, country, etc. The serial# MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 15-2 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) is the equivalent of all this information. In most cases, when prompted for serial#, entering the ? character will provide you with a list of serial#'s and a written description. - You don't need to include your 'return address' (Magnum does this for you). - You can compose the message once, then send CC's (carbon copies) to other addresses without having to re-enter the message. - You can request a 'return receipt' to notify you that the message you sent was received by the addressee. - You can rest assured that the message will not get 'lost' or go to a 'dead box' due to illegible writing, or that the postal workers will go on strike! - You can even send 'Junk Mail' (goes to every Magnum system on the mail network associated with AMMO). - You can send 'private mail'. - etc, etc. By way of example, let's suppose that you are XYZ Corporation with an office in Los Angeles (USA). XYZ Corporation also has branch offices in Chicago (USA), New York (USA), Tokyo (Japan), London (UK) and Bonn (Germany). Each location is running a Magnum System as follows: Location Magnum Serial# ------------- -------------- Los Angeles 1991000001 Chicago 1991000002 New York 1991000003 London 1991000004 Bonn 1991000005 Tokyo 1991000006 To complicate things further, each location is in a different time zone, thus making voice communications difficult in terms of time coordination. Each location needs to communicate vital information with all other offices. In terms of distance, The Los Angeles office is closest to the Chicago office, which in turn is closest to the New York office, which in turn is closest to the London office which in turn is closest to the Bonn office which in turn is closest to the Tokyo office (the exact order we've listed them in the above chart). Now, suppose that someone in the New York office needs to get a message to the London office. They would call the NY BBS with their modem or via 'Pipe Module' on their LAN and enter a message to someone specific at the London BBS. At a predetermined time, the Magnum system in NY "calls" the Magnum system in London and transfers that message (along with any other messages targeted at the London office from New York); during that same transfer, any mail from the London office targeted to the NY office are also transfered. This is known as 'direct' (or point-to-point) RMAIL. Now, suppose AMMO links are set up such that the Los Angeles and Chicago offices set up their Magnum systems to exchange mail once (or twice, or as many times as you wish) every day (or twice a week, or as many times as you wish). Likewise, the Chicago and New York offices are set up to MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-3 exchange mail at some predermined time schedule. The same with the New York<-->London office, the London<-->Bonn office, and the Bonn<-->Tokyo office. XYZ Corporation now has RMAIL capabilities from any of their 6 offices to any other of their 6 offices. In that each office has an AMMO link between their neigboring or closest office, phone costs are minimized. Someone in the Bonn office could send someone at the Chicago office a public (or private) RMAIL message by specifying the Chicago serial# and the ID of the person at that system. In that the Bonn office is linked with the London office, the message first goes to the London office, then to the New York office, and finally to its destination in Chicago. If it is a private message, the users at the London and New York offices will never know about the message. This is known as 'indirect' (or 'store-and-forward') RMAIL. If the volume and frequency of mail between the Bonn and Chicago offices are higher than the other four, a direct link between the Bonn and Chicago office can be set up as well as the existing links. Each Magnum system can have as many links as is desired, and can be set up to exchange mail as many times as desired with whatever systems it desires! We've defined 'direct' (point-to-point), and 'indirect' (store-and-forward) AMMO capabilities so far. In our examples, we spoke of exchanging mail to a specific person (ID) at a specific city (serial#). We also have BROADCAST capabilities. A BROADCAST is where you don't enter a message to a specific user or even to a specific serial#. You enter a message to ALL, and use the word BROADCAST as the RMAIL serial#. This means that every Magnum system on the link will receive the BROADCAST message and address it to ALL. BROADCAST capability is a quick way to post a general message to ALL users on ALL serial#'s on the AMMO link. This has advantages and disadvantages. The advantage to this should be quite obvious; the disadvantage of having MANY systems on the 'link' is that a BROADCAST message could be abused and perceived by many of the users on other systems as 'junk mail'... much the same way as your receiving 'junk mail' at your residence in your mailbox. There are only two possible addressee's of a BROADCAST message: ALL or SYSOPs. If SYSOPs, the message is broadcasted only to the SYSOPs on the AMMO link. In addition to DIRECT, INDIRECT, and BROADCAST mail, ECHO mail also exists. ECHO is similar to 'store-and-forward', however ECHO modifies this to 'store-post-and-forward'. In other words, if someone at the Chicago office chooses to send a message to someone at the Bonn office, the links that it goes through (New York, London) will also post this message on their systems so that the users of their systems can also read and respond to this message. We've covered four types of RMAIL: DIRECT, INDIRECT, BROADCAST, and ECHO. In addition to the four types, all of the usual Magnum mail features can also be used: CC's (Carbon copies), receipts, message forwarding, etc. After you create a message, you can send CC's to both users on the system you've entered the message on, and to remote users on remote systems. You can forward a message to a user on a remote system. You can also request a receipt to be generated and sent to you when the addressee of a message you sent (either local or remote) MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 15-4 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) receives your message. As in the past, the Notepad can be used to contain a list of CC's to send a message to (see the chapter entitled "The NotePad Facility"). With the introduction of RMAIL, the CC's can also contain addresses. See the chapter entitle "The NotePad Facility" for an example of how your users can use the notepad to contain CC lists to both local and remote users. So far, our example situations have been with a small, 6-office Magnum network with only one or two links at each system. Even this small system could have any of its systems linked with any other of its systems. The Tokyo office might open two or three more branches of XYZ Corp in neighboring cities. If it has Magnum systems set up in each of those cities, links from the Tokyo office could also be set up to the other three. It can even exclude those links from its Bonn link (a closed local network) as opposed to making it part of the wide network. There is no limit as to how many systems (serial#'s) can be linked together, and no limit as to how many links each system can have. However, there is a limit of 500 'store-and-forward' serial#'s which can be supported by each direct link, and a limit of 5,000 messages per transmission. We feel that approaching this limit on 'large' systems would be unlikely. ------------------------------------------------------------------------ AMMO - Account Setup: --------------------- Like your USER accounts (each user has an ID number and occupies a record in your USER database), your MAIL accounts also have an ID number and occupy a record in your USER database. A mail account is an AMMO 'LINK' between your system and the system you're setting a LINK with. To set up a mail account (LINK) with another AMMO system, you'll need to coordinate the effort with the Sysop at the system you'll be linking with. Using the "Gilmore Systems BBS" in Southern California (serial# 1989070000) as an example, and YOUR BBS (assume your serial# is 1990000000), follow these directions: 1) Log onto your own BBS locally (* LOGON at the MBBS "Command => " prompt). Log on as a NEW user with a name something like: Firstname=GILMORE, Middlename=SYSTEMS, Lastname=BBS Choose a password and write it down. Complete the logon procedure, write down the ID number assigned to this account, and log off. 2) Call our BBS and leave a message that you'd like to establish an AMMO link with us. Give us: A) Your BBS name. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-5 B) The ID number and PASSWORD from step 1. C) Your modem telephone number. D) Preferred days/times you'd like for your system to call ours (this is optional). 3) Call our BBS back in a day or so and we'll have a message for you stating A,B,C and D of step 2 above for the account we've set up for your system. 4) Log onto your own BBS locally (* LOGON at the MBBS "Command => " prompt). Log on as SYSOP this time. If you don't have your COLOR settings ON, we suggest you turn them on for this logon. A) Go into the SYSOP Menu, USER database area. B) Pull up the record of the ID number you gave us the day before. C) Change TYPE to M (enter the word TYPE and press ENTER; you'll be prompted for new TYPE; respond with M for MAIL). After you've changed the TYPE to M, the remaining fields to fill in will appear in RED. D) Change SYSTEM_SERIAL# (enter the word SYSTEM_SERIAL# and press ENTER; you'll be prompted for new Serial#;ID;password) Enter the Serial# of the system you'll be setting up a link with (in this case, our system), followed by a semicolon, the ID number we gave you, another semicolon, and the password we gave you. E) Note that PHONE1 and PHONE2 have been changed to DIALCMD1 and DIALCMD2 for MAIL accounts. These fields should hold the modem commands necessary to dial the remote BBS with. These two fields are concatenated (treated as one) when Magnum dials this account. For example: DIALCMD1=ATH0S7=60,DT DIALCMD2=1-818-706-9805 Note the S7=60 portion tells your modem to wait up to 60 seconds for a connection with each dial attempt. AMMO only tries 20 times before giving up. 20 tries at 60 seconds/try = 20 minutes. F) Change all other fields in RED color to whatever is appropriate. Make sure we have access to the message conferences you wish. G) Assign us to a MSGGRP. For example, MSGGRP of 3 means that you'll need to create the file MSG3.GRP in your SESSION DIRectory. If you're NOT using the 'Extended MsgBase' module, the contents of this file should be one ASCII text line as follows: 0 RWL ; This means that we'll have read/write/list access to MsgBase 0. If you ARE using the 'Extended Msgbase' module, give us access to the MsgBases you wish us to have access to. Example: 0 RWL ; 3 RWL ; 157 RWL ; H) Be CERTAIN to change the RMAIL field to Y (yes)!!!! I) Add our Serial# to the AMMO.MAG file in your SESSION MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 15-6 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) DIRectory. If the file AMMO.MAG doesn't exist in your SESSION DIRectory, you'll need to create it. Without it, AMMO/RMAIL is "not installed". This is an ASCII text file with the following format (via example): 1989070000(0):Gilmore Systems Magnum BBS ; BBS name 1989110006 ; \ 1990020045 ; \ ____ Maximum of 500 supported serial#'s 1992030102 ; / accessible to the above as "store 1991050607 ; / and forward" serial#'s. 1989110006(0):TJD Software BBS ; BBS name 1992030102 ; ----> "store & forward" to this serial# 1991020321(22):ABC Corp BBS The number in parens indicates which msgbase incoming mail from this serial# will be placed. If you are NOT using the optional "Extended MsgBase" module, then this number MUST be 0. The format of the file is simple: Direct_Link_Serial_Number(MsgBase):BBS NAME ; Optional Comment Optional_Store_and_Forward_Serial_Number_1 ; Comment Optional_Store_and_Forward_Serial_Number_2 ; Comment Optional_Store_and_Forward_Serial_Number_N ; Comment Next_Direct_Link_Serial_Number(MsgBase):BBSNAME ; Comment etc, etc, etc Note that normally any 'store-and-forward' links should also appear as either a 'direct-link' somewhere in the file, or should also appear as a 'store-and-forward' link under more than one 'direct-link'. Mail coming in to your BBS from whatever Serial#, will be placed in the MsgBase specified in parenthesis next to the serial# above. However, if a 'reply' to a message is coming in, it will be placed in the same MsgBase and conference area as the message it's replying to. If any 'store-and-forward' serial#'s are listed below a 'direct-link' serial number (but before the next direct-link serial#), messages for those serial#'s will be sent to the direct-link serial# when connected. For example, if you're in New York and you have a 'direct link' with us, then you might consider having 'direct links' with other Magnum systems in your area. You could then list those serial#'s as optional store-and-forward numbers under the direct link with our serial# so that users of those serial#'s could send us mail via your BBS. Remember, a 'direct-link' entry in the AMMO.MAG file consists of a 10-digit serial#, immediately followed by a MsgBase in parenthesis, which is immediately followed by a colon (:) character, which is immediately followed by descriptive text of the BBS. A 'store-and-forward' link entry (a serial# in which messages are stored on your BBS and then forwarded to a 'direct-link' serial#) is simply a MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-7 10-digit serial# (and nothing else) which is listed below a 'direct-link' serial# (and before the next 'direct-link' serial#). Each 'direct-link' serial# can be followed by as many as 500 'store-and-forward' serial#'s. When a 'direct-link' serial# is connected with your BBS for AMMO RMAIL exchange, the 'direct-link' serial# receives all mail targeted for its serial# along with all mail targeted for the 'store-and-forward' serial#'s listed below it. Any mail sent to the 'direct-link' serial# (including those of 'store-and-forward') will be marked by AMMO as being "sent" on your system, and the 'store-and-forward' messages will be considered "unsent" on the receiving system until they reach their target BBS serial#. IMPORTANT: With the exception of 'replies', Incoming mail will be placed in the MsgBase you provide in parens! The actual Conference Area the message will be placed in will be the same as the conference area on the sending machine (regardless of which MsgBase it's coming from). Therefore, links should have access to ALL conference areas of your incoming MsgBase (A-Z), and ALL conference areas in your MsgBase (whichever it is) should be defined and used! FOR THIS REASON WE STRONGLY RECOMMEND THE 'EXTENDED MSGBASE MODULE'!! NOTE: During mail processing, OUTGOING mail will be named RMnnnnnn.ZIP (in the RMAILOUT directory), and INCOMING mail will be named RMnnnnnn.ZIP (in the RMAILIN directory). Note that nnnnnn will be the userid of the mail account on YOUR system. INFO: The RMAILOUT and RMAILIN directories are created for you automatically. These are subdirectories of the main MSG DIRectory. WARNING: NEVER, NEVER, NEVER GIVE OUT AMMO MAIL ACCOUNT INFORMATION TO ANYONE BUT THE SYSOP OF A MAGNUM SYSTEM YOU'RE ESTABLISHING A DIRECT LINK WITH!! To start an AMMO exchange of RMAIL: ----------------------------------- There are two ways of starting an AMMO exchange of RMAIL with any particular link you're set up for: 1) Manually 2) Automatically With the manual method, enter the command at the MBBS.EXE "Command => " prompt: * RMAIL node:id Let's suppose you've established a mail account with us. Suppose that the ID number on your system that you've set up for us was /999. Now suppose that you want Node 2 on your system (or any other MODEM node on your system) to perform an AMMO RMAIL exchange with us. The actual command you'd issue is: MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 15-8 Magnum-to-Magnum Remote Mail (AMMO / RMAIL) * RMAIL 2:999 The rest is automatic! You can walk away at this point. Your system will gather up all messages targeted for our BBS and then call our BBS using node 2's modem with the DIALCMDx information in account /999. Your system will try up to 20 times to get a connection with our BBS before it gives up. If it gets connected, it will log on automatically and our BBS will gather all mail targeted for your system. The two systems will then exchange mail, hang up, process mail, and end the session. Note that either of our systems can call the other at any given time. To automate the "* RMAIL Node:ID" command, simply put it in your MBBS.ACE file to execute at whatever days you wish, and as many times as you wish. See the chapter entitled "ACE - Magnum's Event Handler". Typically, busy systems need to set aside times designated for mail, otherwise the mail account may never make it online! This can be accomplished with the "x CALLS MAIL" command to accept calls from mail accounts on node x - all other callers (user accounts) will be denied access. To revert back to normal operations, the command "x CALLS ALL" must be issued for node x. In this normal mode of operation, Magnum will accept calls from both Users and Mail accounts. Once again, this command can be placed in your MBBS.ACE file. After a mail caller calls, processing of mail begins immediately after their id and password have been successfully entered. All usual display of .BBS files are omitted, and "Press Enter..." prompts are omitted. The entire process is automated between the two machines. However, there is one .BBS file which, if exists, will be processed/displayed. This file is RMAIL.BBS (in the SESSION DIRectory) if it exists. This file serves no real purpose at this time, but is reserved for future expansion. INFO: The "* RMAIL node:id" command actually starts a LOCAL session. You must NOT be online on the local (console) node at the time of this command! AMMO is online on the local (console) node when the RMAIL command is given. It uses the modem and configuration for the 'node' number you supplied, therefore, no one must be online on node 'node'. RMAIL only works with 'nodes' (STARTUP.n) that were configured as 8 databits, 1 stop bit, No parity. AMMO assumes a modem with the "AT" command set, although this may not be necessary for proper operation. Entering Messages to Users on Other Systems: -------------------------------------------- There are 3 ways to enter a message to users on other systems: 1) Use the $ character at the ADDRESSEE prompt (who is msg to?). Enter Serial# at the Serial# prompt (? provides serial# list). Enter /ID of user at that serial#. 2) Use the $ character at the ADDRESSEE prompt (who is msg to?). MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Magnum-to-Magnum Remote Mail (AMMO / RMAIL) Page 15-9 Enter BROADCAST at the Serial# prompt. Enter ALL or SYSOPs. This method will broadcast your message to all systems allowed to exchange messages with the system you entered the message on. In turn, these systems will broadcast your message to all systems allowed to exchange messages with their systems, etc. This will get your message onto many systems very quickly. 3) When reading a message from a remote system/user (FROM field starts with the $ character), choose [R]eply at the message disposition prompt. Simply reply to the message as you would any other message. Tech Note: ---------- With the advent of 'remote mail' capabilities in conjunction with the ability for the sysop to select the MILC command character for their system, you may be wondering if messages using MILC commands on one system are executable on other systems... especially if the two systems are using different MILC command characters! The answer is YES. Regardless of the MILC command character, any message that works on the originating system will also work on any other system when transferred via remote mail. However, the commands that are available (executable) in a remote message (one received from another system) are limited to the MILC commands you specify in the DISP_CMDS parm of your STARTUP.n file for that node. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank Closing Remarks Page 16-1 Congratulations! You've just completed reading the documentation for the Gilmore Systems Magnum BBS System for OS/2. We hope that you'll have many years of ongoing satisfaction with this product. If you have any problems, please leave them in the form of a "[C]omment to Sysop" or message on our BBS at (818) 706-9805. We will have a response for you usually within 24 hours. ALL TECHNICAL SUPPORT QUESTIONS AND PROBLEMS WILL BE HANDLED EXCLUSIVELY VIA OUR BBS AT (818) 706-9805. IF YOU CALL ON OUR VOICE LINE WITH A TECHNICAL SUPPORT QUESTION OR PROBLEM WHICH REQUIRES US TO CALL YOU BACK, WE WILL CALL YOU BACK COLLECT! HAVE YOUR SERIAL NUMBER READY (YOU WILL BE ASKED FOR IT). We've set up a special section on our BBS for Magnum Sysops (file area 'S' and message conference area 'S'). This will enable you to converse with other Magnum Sysops, exchange ideas and information, ask questions, etc. We encourage regular checking in from time to time. Other Sysops have already wrote some external programs for Magnum which they've uploaded (you can download these anytime). If you wish information on the record layouts for Magnum's databases, please inquire within - we encourage 3rd party development, but do not support it (3rd party developers must support their own products). So far, Magnum BBS will run with almost any modem. Your modem should be capable of hardware flow control (CTS/RTS) and your modem cable must have RS-232 pin numbers 4 and 5 wired to carry these signals - some cables are not wired this way. This is especially the case when the DTE baudrate (the speed of computer to modem) is higher than that of the modem's DCE baudrate (the speed of the modem over the phone lines). Some internal modems force the carrier signal high (constantly on) - your modem needs to report carrier to Magnum in a realtime fashion (the true state of the carrier signal - for modems with the "AT" command set, this is usually accomplished with the &C1 command). Your modem must also be configured to respond to the DTR signal - in other words, when Magnum closes the comport, your modem should respond by dropping the line - if your modem uses the "AT" command set, see the &Dn command in your modem's user manual. For modems with the "AT" command set, see the S10 register in order to make your modem drop the connection when carrier is lost. Keeping things in perspective, your modem is your computer and BBS's only link to the outside world. It is important that you not cut corners in this arena. Magnum BBS and your modem(s) have a synergistic relationship and we suggest you use a name brand modem which has been successfully used in the public arena for a long time. The STARTUP.1 file included with your shipment contains the modem sequences for the MultiTech 224E 2400-baud modem with a DTE speed locked at 9600 baud. The STARTUP.2 file included with your shipment contains the modem sequences for the USRobotics HST dual-standard modem (9600/14400 baud) with a DTE speed locked at 19200 baud. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page 16-2 Closing Remarks The STARTUP.3 file included with your shipment contains the modem sequences for the Hayes V.42 9600-baud modem with a DTE speed locked at 19200 baud. THIS IS EXPERIMENTAL (we only had this modem for 30 days). Other modem startup strings, etc, are supplied in a file called MODEMS.TXT on your distribution disk. Also on your distribution disk, is a file called MAGNUM.H which are the structure layouts (in C) of the databases used by Magnum (USER, MSG, RJE, FILE, UTILIZ). With this information you may write your own programs to manipulate the databases used by Magnum. By all means, give us a call if you have ANY questions or concerns about accessing the data in these databases. Should you write programs which actually WRITE to or APPEND to these databases, be sure to adhere to standard record-locking conventions. If you'll be appending to the USER database, give us a call for important information you'll need to know - it's not as simple as just "appending" a record (all other databases EXCEPT the USER database are straight-forward if appending). IMPORTANT CONSIDERATIONS: ------------------------ ALWAYS, ALWAYS have a backup copy of your databases prior to running the MBBSEXEC.EXE program. Any errors (ie: typos, logic, etc) in your .MEX files can ruin your databases! We're running our system such that an "ACE" command starts a .cmd file which copies the databases to a different directory prior to running the mbbsexec.exe program for maintenance. If you're writing a new '.mex' file, you should consider setting up a test system to test it out with - do not experiment on your production system without full backups of the databases! Magnum uses variables @Z0, @Z1, @N0 and @N1 internally when invoking external programs such as pkzip2.exe, pkunzip2.exe, arc2.exe, chkansi.exe, etc... bear this in mind when using the @R1, @Fx and @Qx MILC commands. Be advised that the RJE menu's [K]ill option will only kill the program it started - not any children of that program. IMPORTANT INFORMATION ABOUT COM0x.SYS DEVICE DRIVERS: ---------------------------------------------------- If you're running OS/2 SE 1.2 or OS/2 EE 1.2 on an IBM PS/2 machine: The COM02.SYS device driver may or may not work with your version of OS/2 1.2. To find out if your COM02.SYS driver is the proper one for your system, execute the following command (comes with the Operating System): SYSLEVEL.EXE After a couple of minutes, you'll get the CSD level. For OS/2 version 1.2 SE, the CSD level should be XR04073 or greater. For OS/2 version 1.2 EE, the CSD level should be XR04084 or greater. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Closing Remarks Page 16-3 If your CSD level is less than the above, the COM02.SYS device driver for your operating system is defective. You can correct the problem by either using the COM02.SYS device driver supplied with OS/2 ver 1.1 or by updating your system to the latest CSD level. Unfortunately, IBM is the only company which supplies CSD (customer service disks) updates which can be obtained by contacting your local authorized IBM dealer. OS/2 1.2 EE CSD levels WR04097 and WR04098 has a problem in the kernel relating to auto-buffering regardless of whether your UART supports auto-buffering or not! Because the problem lies within the kernel it cannot be fixed by simply replacing the COM0x.SYS or other device driver. The "fix" is one of two options: 1) Go back to a CSD level earlier than WR04097 or 2) Upgrade to OS/2 1.3 EE. Since there will be no more CSD's released for 1.2, the "fix" is to upgrade to OS/2 1.3 EE. OS/2 Version 1.3 As of this writing, IBM OS/2 v1.3 SE and OS/2 v1.3 EE has no known problems. OS/2 Version 2.0 Magnum BBS has been running successfully on all releases of OS/2 2.0 from the initial Microsoft beta 2.0 (before IBM took it over) to the final "GA" version of IBM OS/2 2.0. MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank Index Page I-1 - . - .SNP ..................... 9-5, 9-57 - < - <F7> ..................... 5-15, 7-4 - @ - @# ....................... 4-19 @A ....................... 4-2 @B ....................... 4-3, 4-6, 4-30, 4-50 @C ....................... 4-5 @D ....................... 4-8 @E ....................... 4-10, 4-13, 4-14, 4-15, 7-36 @I ....................... 4-16, 4-17, 9-3, 9-4, 9-7 @J ....................... 4-18 @K ....................... 4-19 @L ....................... 4-20 @M ....................... 4-21 @N ....................... 4-3, 4-6, 4-16, 4-22, 4-23, 4-24, 4-31, 4-32, 4-45, 4-50, 6-19 @O ....................... 4-6, 4-25, 4-27, 4-44, 7-30 @P ....................... 4-3, 4-30 @R ....................... 4-31 @S ....................... 4-33 @T ....................... 4-34 @U ....................... 4-6, 4-35, 4-44, 4-49 @V ....................... 4-39, 4-44 @W ....................... 4-41 @Y ....................... 4-18 @Z ....................... 4-3, 4-4, 4-6, 4-16, 4-31, 4-32, 4-42, 4-43, 4-50, 6-19 @\ ....................... 4-46 - A - ACE ...................... 2-1, 5-4, 5-10, 5-11, 5-13, 6-3, 8-1, 8-2, 8-3, 8-4, 8-5, 15-8, 16-2 AMMO ..................... 2-2, 6-4, 7-27, 15-1, 15-2, 15-3, 15-4, 15-5, 15-6, 15-7, 15-8 ANNOUNCE ................. 1-8, 2-1, 2-7, 5-1, 5-6, 5-7, 6-2, 8-3, 8-4 ANSI-EDITOR .............. 7-11 ARQ ...................... 7-18 - B - BELL ..................... 5-1, 5-2, 5-3, 7-4 Blockwrite ............... 5-12 Blog() ................... 9-28, 9-36, 9-37, 9-56, 9-59 - C - MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page I-2 Index CC List .................. 12-1, 12-2 CTS ...................... 1-1 Call() ................... 9-28, 9-45, 9-47 Carrier .................. 1-7, 1-8, 4-6, 5-1, 5-2, 5-8, 5-9, 6-1, 9-12, 16-1 Chat ..................... 1-2, 1-14, 1-23, 2-6, 3-3, 4-28, 5-9, 5-15, 6-19, 7-4, 7-5, 13-2 Child .................... 1-7, 1-23, 2-1, 2-5, 4-28, 4-39, 4-40, 6-1, 6-3, 6-15, 7-8, 7-14, 7-24, 7-35, 7-37, 9-31, 9-52, 9-56 Clog() ................... 9-28, 9-37, 9-46, 9-59 Compression .............. 2-2, 2-4, 3-4, 4-37, 6-4, 6-5, 6-6, 6-8, 7-2, 7-6, 7-22, 7-23, 9-7 Crash Recovery ........... 7-18 - D - DCE ...................... 1-8, 16-1 DISP_CMDS ................ 1-17, 4-1, 4-46, 4-47, 7-30, 15-9 DTE ...................... 1-8, 1-10, 7-7, 16-1, 16-2 DTR ...................... 1-1, 1-4, 16-1 Door ..................... 2-5, 11-1 - E - ENDNOW ................... 5-8, 5-9 EQUATE ................... 9-44, 9-53, 9-54, 9-58 Environment .............. 4-8, 4-43, 6-1, 7-23 Error Correction ......... 4-37, 9-12 Exit() ................... 9-28, 9-29 External File Compression 2-2 External file compression 2-2 - F - FILE MENU ................ 1-22, 1-23, 1-24, 3-4, 4-7, 6-11, 6-12 FORCEOFF ................. 5-2, 5-3 FSTART ................... 9-57, 9-58, 9-59 FSTOP .................... 9-57, 9-58, 9-59 File group ............... 4-38, 9-7, 14-1 Form Letters ............. 9-1, 9-34 - G - Goto() ................... 9-47 - I - If() { ................... 9-59 Indirect addressing ...... 4-46, 4-49, 4-50, 4-51, 4-52, 9-42, 9-43, 9-61 Initialization ........... 1-9, 3-2, 4-31, 9-2, 9-13 Input() .................. 9-28, 9-38, 9-46 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Index Page I-3 - L - LAN ...................... 1-2, 1-5, 1-6, 1-8, 2-1, 7-4, 7-34, 10-1, 13-1, 13-2, 13-3, 15-2 LINE-EDITOR .............. 7-12 LOCKOUT .................. 5-5, 7-13 LOGON .................... 1-2, 1-5, 1-15, 1-20, 2-2, 2-3, 2-7, 3-1, 3-2, 3-3, 4-28, 4-33, 5-1, 5-3, 5-4, 5-6, 5-7, 5-13, 6-2, 6-3, 6-4, 6-8, 6-9, 6-10, 6-13, 6-16, 7-1, 7-2, 7-15, 7-23, 7-33, 15-4, 15-5 Log() .................... 9-32, 9-33, 9-36, 9-37, 9-56, 9-59 - M - MAIN MENU ................ 1-16, 1-18, 1-22, 1-23, 1-24, 1-25, 2-2, 4-33, 6-4, 6-11, 6-12, 7-1, 7-3, 7-4, 7-5, 7-6, 7-7, 7-8, 7-9, 7-25, 7-34, 7-36, 11-1 MBBSINIT ................. 1-26, 2-1, 3-1, 3-2, 4-37, 5-6, 5-7, 6-2, 9-2, 9-3, 9-56 MESSAGE MENU ............. 1-22, 1-23, 1-24, 4-31, 6-11, 6-12, 7-3, 7-9, 7-10, 7-11, 7-12, 7-13, 7-14, 7-22 MNP ...................... 1-10, 1-12, 1-13, 7-18, 9-12 Magnum-to-Magnum ......... 5-14, 7-27, 15-1, 15-2, 15-3, 15-4, 15-5, 15-6, 15-7, 15-8, 15-9 Mail account ............. 15-4, 15-7 Mailing Labels ........... 9-1, 9-32, 9-34 Marked files ............. 7-15, 7-24 Marking .................. 7-12, 12-1 Message group ............ 9-7 - N - NotePad .................. 6-20, 7-12, 12-1, 12-2, 15-4 NotePad Facility ......... 12-1, 12-2 - O - Offline .................. 10-1, 11-1 - P - POWER .................... 3-1, 4-15, 4-17, 4-23, 4-24, 4-31, 4-45, 9-22, 9-24, 9-56, 11-1 - R - RJE ...................... 1-13, 1-17, 1-22, 1-23, 1-25, 2-1, 2-2, 2-3, 2-5, 2-6, 4-10, 4-11, 4-12, 4-28, 4-37, 4-39, 4-40, 6-2, 6-7, 6-8, 6-11, 6-12, 6-16, 7-2, 7-3, 7-7, 7-8, 7-14, 7-23, 7-24, 7-35, 7-36, 7-37, 9-1, 9-3, 9-5, 9-7, 9-8, 9-11, 9-12, 9-13, 9-21, 9-27, 9-56, 11-1, 11-2, 13-3, MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Page I-4 Index 16-2 RMAIL .................... 1-17, 5-14, 7-31, 15-1, 15-2, 15-3, 15-4, 15-5, 15-7, 15-8 RTS ...................... 1-1 Redirected serial port ... 1-8 Refresh .................. 5-10 Remap .................... 2-1, 13-3 Remote Mail .............. 1-17, 2-2, 4-38, 5-14, 6-4, 7-31, 9-7, 12-2, 15-1, 15-2, 15-3, 15-4, 15-5, 15-6, 15-7, 15-8, 15-9 Remote Snoop ............. 1-21, 7-33 Restore_data() ........... 4-47, 9-51 Return(x) ................ 9-46, 9-58, 9-60, 9-61 - S - SNOOP .................... 1-21, 1-25, 5-2, 7-33 STARTUP .................. 1-1, 1-3, 1-4, 1-5, 1-6, 1-8, 1-9, 1-10, 1-14, 1-15, 1-17, 1-22, 1-26, 2-1, 3-1, 4-37, 4-39, 5-4, 5-7, 5-13, 5-14, 5-16, 6-1, 6-2, 6-3, 6-8, 6-13, 7-3, 7-6, 7-8, 7-14, 7-16, 7-22, 7-35, 7-37, 8-1, 8-3, 9-7, 9-12, 9-50, 9-51, 9-62, 11-1, 13-1, 13-2, 13-3, 15-9, 16-1, 16-2 SWITCH ................... 1-4, 5-2, 5-3, 5-4, 5-15, 7-4, 7-6, 7-8, 7-17, 7-33, 9-7 SYSOP MENU ............... 1-7, 1-22, 1-24, 1-25, 5-5, 6-4, 6-11, 6-12, 7-1, 7-8, 7-25, 7-26, 7-27, 7-28, 7-29, 7-30, 7-31, 7-32, 7-33, 7-34, 7-35, 9-27, 14-1, 15-5 Save_data() .............. 4-47, 9-51 Security Level ........... 1-15, 1-18, 1-19, 1-22, 1-23, 1-24, 2-2, 2-7, 4-20, 4-36, 5-5, 6-9, 6-11, 6-12, 7-3, 7-4, 7-8, 7-16, 7-25, 7-29, 7-30, 9-1, 9-6, 9-12, 9-17, 9-21, 9-22, 9-53, 14-1, 14-2 Server ................... 1-2, 1-6, 1-8, 13-2, 13-3 Shutdown ................. 5-1, 5-3, 5-8, 5-9, 7-33, 8-4 Slog() ................... 9-28, 9-36, 9-37, 9-59 Sysbell .................. 5-11 System() ................. 9-28, 9-49, 9-51, 9-60 - T - TIME+NNN ................. 5-6 - W - While() .................. 9-28, 9-39, 9-57, 9-59 While() { ................ 9-59 Workstation .............. 1-2, 13-1, 13-2, 13-3 - Y - Ymodem-G ................. 1-7, 7-15, 7-18 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems Index Page I-5 - Z - Zmodem ................... 7-18 MAGNUM BBS (r) for OS/2 - (C)Copyright 1989,1992 Gilmore Systems This Page Intentionally Blank